A good changelog is not a press release. It is a quiet, honest record of what changed in your product, written for the person who uses it every day. The customer scanning your changelog is not your marketing audience. They want three things, in order: what changed, whether it affects them, and what to do next.
Lead with the verb
Every entry should start with a verb in the past tense. "Added", "Fixed", "Improved", "Removed". The verb does most of the work. A reader who skims the bolded openings of ten entries should still come away with a clear picture of where the product moved.
Bad: "We are happy to announce a new dashboard." Good: "Added a new analytics card to the project dashboard."
Use categories sparingly
Most teams default to four buckets — new, improved, fixed, announcement — and that is usually enough. Resist the temptation to invent a fifth category for one off entries. Categories work when readers can predict what fits in each one. The moment you need to justify a label, you have lost the reader.
Cut the meta-narrative
Your changelog is not the place to explain why you shipped something, unless the explanation is the change. Skip the paragraph about the team's roadmap, the marketing copy about what's coming next, and the apology for taking so long. The next entry is your "what's coming next." The fact that you shipped is the apology.
Ship more often, in smaller pieces
A changelog that updates twice a month feels alive. One that updates twice a year feels abandoned. If you find yourself batching three weeks of work into a single Friday entry, split it. Customers read one or two-bullet entries faster than they read a wall of text, and they trust a product that keeps moving.
Pin what matters
Most changelog tools (including this one) let you pin an entry to the top. Pin sparingly. A breaking change deserves a pin until customers have had time to migrate. A new feature you are proud of does not.
Write for the reader who knows nothing
The customer reading the entry might have signed up yesterday. They do not know that "the v2 migration" or "the new ingestion pipeline" means anything. Spell out enough context that a fresh reader can follow. Link to the docs page when the context would take more than a sentence.
A template
Here is a structure that works for almost every entry:
- One-line summary, starting with a verb. This is the title.
- One short paragraph with the why, only if the why is non-obvious from the title.
- A list of specifics, if there are more than two. Otherwise prose.
- A link to the docs page for the new behavior, when relevant.
Keep the whole thing under 150 words. If you cannot, split it into two entries.
That is the entire system. The hard part is shipping often enough that you need it.