Migrating a changelog off a Notion page, a hosted widget such as Headway, or a Google Doc is four decisions rather than a copy and paste: where the entries live from now on, what address each entry answers at, what happens to the links people have already shared, and who writes the next entry. Move the text first and those four get decided for you by whatever the new tool does by default. Decide them first and the move itself takes an afternoon.
In a changelog migration the prose is the easy part and the part nobody loses. What goes missing is everything around the prose, because in a Notion page or a Google Doc most of it was never written down as data in the first place. Before touching the new tool, list what you are carrying:
A changelog entry that arrives in the new tool with prose and nothing else is not migrated, it is retyped. The test is whether you can sort the archive by date, filter it by category and link to one entry on its own. If the answer to any of those is no, the structure did not come across, and the structure is what a reader uses.
The three sources people migrate a changelog off lose different things, because they store different amounts of structure. A Notion page keeps some ordering and some dates. A hosted changelog widget keeps entries as records, which is more structure than either document form, but the page it renders is on somebody else's domain. A Google Doc keeps almost nothing but the words.
| Moving from | What carries over | What has to be rebuilt |
|---|---|---|
| A Notion page | The prose of every entry, and the date where you typed one | Per-entry addresses, any feed, the category labels, and the ordering rules |
| A hosted changelog widget | Entries as separate records, with their dates and categories | The page on your own domain, its address, and where the widget sat inside your product |
| A Google Doc | The prose, usually in one run, often with no reliable per-entry dates | Entry boundaries, dates, categories, addresses and anything a reader could subscribe to |
A breaking change is the one entry a reader cannot skim. It has to name what stops working, the date it stops, and the replacement — and no common changelog standard gives it a category of its own, so the title and the body carry it.
Market4 turns one release note into a changelog page, a blog post, a mail-out and a week of social posts — and then tells you which of them brought anyone back.
Every old changelog address that somebody has already put in a support reply, a release e-mail or a tweet is a link you now control the fate of. There are three honest options and one dishonest one. Redirect the old address to the matching new entry, which is the option that keeps the reader's place. Redirect everything to the new index, which is worse but survivable. Leave the old page standing and stop adding to it, with a line at the top pointing at the new one. The dishonest option is deleting the old page and letting the links break, which is invisible to you and only visible to the person who followed one.
A hosted changelog is where this bites hardest, because the old addresses are on a domain you do not own and cannot add a redirect to. If your entries lived on a vendor's subdomain, plan on the old links dying and on going through your own docs and canned replies to find the ones you can fix yourself.
The shape of a changelog is three choices, and a migration is a cheap moment to make them, because after the move every change is an edit to live entries. Decide whether an entry is labelled by version or by date, decide which categories exist, and decide the smallest thing that earns an entry. Write the answers down next to the archive; the point is that the next person adding an entry does not have to guess.
Two decisions in a changelog migration are worth making deliberately rather than inheriting. The first is whether you keep the entries that predate the migration at all: an archive of thin entries written to a different standard drags the average down, and moving them unchanged is a choice to keep them. The second is whether the changelog stays a place people visit or becomes something that also arrives, by feed or by e-mail, in which case the subscriber list is part of the migration and not an afterthought.
Publishing a migrated archive in one burst is the step that surprises people. If the new changelog sends e-mail or serves a feed, loading forty old entries can announce forty old entries. Check what publishing does before the first load, and load the archive in whatever state does not notify anyone.
Move them if they were written to roughly the standard you want to keep, because an archive with history is evidence that the product has been maintained for years. Start fresh if the old entries are one line each, undated, or written for a different audience. A middle option works too: move the last year, and keep the older ones on the old page with a link, so nothing breaks and nothing embarrassing is on the new page.
They break unless you redirect them. If the old changelog was on your own domain, add a redirect from each old address to the matching new entry, or to the new index if you cannot match them. If it was hosted on a vendor's domain, you cannot add redirects at all, so the old links will die when the account closes. Search your own documentation and support replies for those addresses and fix the ones you own.
One page is enough to read, and not enough to link to. The moment somebody in support wants to answer a question with a note about what shipped in March, they need an address for that note on its own. A single page also cannot be filtered or subscribed to per category. If you are migrating anyway, per-entry addresses cost nothing extra at that moment and cannot be retrofitted cheaply later.
Take them from the release itself rather than guessing. A tag in your repository, a deploy record, or the date on the release e-mail all give a real date for an entry that a document never recorded. Where no record exists, use the month rather than inventing a day, and say so. A date somebody made up is worse than a coarse date, because it looks precise.
Somebody deciding whether to buy your product reads the changelog for something your marketing pages cannot tell them: whether anyone is still working on it, and what happens to them when something changes.
A changelog entry that links well converts better than one that sells. The rule is destination, not persuasion: link where the reader goes to use the thing, and cut every link that exists to move them somewhere you wanted them.
