Changelogs and roadmaps, two different promises#
A changelog records what shipped. A roadmap says what is coming without committing to a date. Conflating them is how a public roadmap turns into a list of missed deadlines and then quietly disappears.
The six changelog and roadmap blocks#
- Roadmap 1: a three-column Now, Next and Later board that publishes order rather than dates. Free.
- Changelog 4: a plain release list with a date rail, every line tagged added, improved or fixed. Free.
- Changelog 1: an editorial release timeline with version anchors and copyable links.
- Changelog 2: a dense changelog with type filters, month grouping and expandable rows.
- Changelog 3: scroll-stacked releases handing over one at a time, each pairing its version panel with what changed and why.
- Timeline 1: a public Now, Next and Later board with vote chips.
Publish order, not dates#
Now, Next and Later is the format that survives contact with reality. A dated roadmap is a set of promises you will break in public; an ordered one is a statement of priority you can reorder without anybody feeling misled. Roadmap 1 and Timeline 1 both use it.
Letting people vote#
Timeline 1 carries vote chips on each card. The counts are display state, so connect them to your own store or feedback tool. Worth deciding before you ship it: whether votes actually influence the order. A vote counter that visibly changes nothing is worse than no voting, because it turns a roadmap into a suggestion box people stop trusting.
Long release histories#
Changelog 2 groups by month, filters by change type and expands rows on demand, which keeps two years of releases readable. Changelog 1 is the editorial alternative where each release deserves a paragraph. Changelog 4 is the plainest, and for most products the plainest is right.
Linkable versions#
Version anchors are copyable links, so a support reply can point at the exact release that fixed something. That is the main thing a public changelog is actually for, and it is the feature most changelogs omit, leaving support to describe a fix instead of linking it.
Writing an entry people read#
- Lead with what changed for the user, not the internal component that changed
- Tag every line added, improved or fixed, so somebody can skim for the one they care about
- Say when a change is breaking, at the top, in plain words
- Link the documentation for anything that needs more than a sentence
- Skip the releases with nothing user-facing rather than padding them
Where these sit#
As their own pages, usually linked from the footer and from a product menu. A new release is also worth a banner for a few days, and the blog card grids handle the longer write-up a significant release deserves.
