Changelog tool checklist: what it should do for you

Every product has a changelog, even if it is only a list in someone’s head. The question is how much work it takes to keep it current and whether the people who care ever see it. For a developer library, a CHANGELOG.md file in the repository may be all you need. For a product whose users never open your repository, a changelog tool has a different job: publishing updates where users are, and telling the people who asked for a change that it shipped.

This guide explains when a file is enough, gives a checklist for choosing a changelog tool, and summarises how three feedback tools package their changelogs.

When a changelog file is enough

If your users are developers who install your package and read your repository, a changelog file is hard to beat. It lives next to the code, it is versioned with it, and conventions like Keep a Changelog give it a familiar shape, with the latest version first.^{Source [1]}

A file stops being enough when:

• your users are not developers and never visit the repository;
• you want to tell specific people that their request shipped;
• updates should appear inside your product, not only on a separate page;
• product, support or marketing people write the entries, not engineers.

At that point you need a changelog page, and usually a tool to run it.

The changelog tool checklist

Not every team needs every item. Read the list, mark what matters to you, and use it when you compare tools.

1. A page per entry, plus the full list

Each update should have its own page with a stable link, so support can send it, search engines can index it and a release can be referenced later. The list page shows everything, newest first.

2. Categories readers can filter

Something like New, Improved and Fixed lets readers skip to what they care about. Our release notes guide explains how to group changes and has a template for each entry.

3. Links to the requests each change ships

The most useful line in a changelog entry is “you asked for this”. Linking an entry to the feedback that led to it shows readers the change came from users, and gives you the list of people to notify.

4. Notifications to the people who asked

A changelog page only reaches people who visit it. The people who voted for or followed a request should hear when it ships, by email or in the product, without having to check. This is the last step of the customer feedback loop.

5. Subscriptions that respect the inbox

Some readers want every update. Offer email subscriptions with a confirmation step, so nobody is signed up by someone else, and a one-click unsubscribe in every email: RFC 8058 defines headers with which a receiving system can process an unsubscribe request in the background without further interaction.^{Source [2]}

6. A feed

RSS is a Web content syndication format.^{Source [3]} Some readers follow products in a feed reader, and some teams pipe feeds into a chat channel. A changelog without a feed asks them to remember to visit.

7. Updates inside your product

A “What’s new” panel or widget meets users where they work. It should point to the full entry rather than duplicating it.

8. Drafts, previews and scheduling

Changes often ship on a schedule. Being able to write an entry ahead of time, share a preview with a colleague and publish at a set time removes the late-night copy-paste.

9. An API and webhooks

If you announce releases elsewhere (a status page, a chat channel, your own docs), an API and webhooks let you automate it instead of copying text by hand.

10. Your brand and your domain

The changelog should look like part of your product. Check whether the tool lets you use your logo and colours, and whether removing the vendor’s branding or using your own domain costs extra.

Keep the changelog going

A tool only helps if entries keep coming. A routine that works without heroics:

1. Write the entry when the work merges, not on release day. The person who built it knows what changed; a short draft is enough.
2. Rewrite for users before publishing. Lead with what people can do now, and link the requests it closes.
3. Batch small fixes. One weekly “Fixed” entry reads better than ten tiny ones.
4. Publish, then notify. Check that the people who asked will be told, and that the entry appears in the product.
5. Look back once a month. If nothing was published in a month when you shipped things, the routine has a gap.

How three feedback tools package their changelogs

Several feedback tools ship a changelog next to the feedback board, which makes sense: the two share the list of who asked. Here is what three of them publish about their changelogs, read on their own pages on the date in the sources:

• Canny offers a changelog widget and a hosted changelog page, and on its Pro plan changelog subscribers get an email automatically when you publish.^{Source [4]}
• Featurebase lists a public changelog page and in-app and email updates from its Growth plan.^{Source [5]}
• hearloop links changelog entries back to requests and emails followers on publish, with an RSS feed.^{Source [6]}

Plans and features change, so check each vendor’s current pricing page before you decide. Our comparison pages put each tool next to UpVoiced feature by feature, with sources.

How UpVoiced handles the changelog

In UpVoiced, which we are building, the changelog is part of the same workspace as your feedback board and public roadmap. Each entry has its own page on your portal, a category (New, Improved or Fixed) and links to the requests it ships, shown as “You asked, we shipped”. Publishing an entry moves those requests to Shipped and can email everyone who followed them; readers can also subscribe by email, with a confirmation step, or follow the RSS and Atom feeds. Entries can be scheduled, and webhooks and the REST API let you announce them elsewhere.

Inside your product, the UpVoiced widget shows the same updates in its “What’s new” tab, next to your ideas and roadmap.

UpVoiced is in development and not open for sign-ups yet; try the fictional demo or request early access.