How to move your changelog without losing your history
Switching changelog tools usually means abandoning years of entries or re-typing them. It does not have to. Here is the order to do it in, and the two things that go wrong.
3 minute read
Changing changelog tools is easy right up to the moment you remember the 180 entries you have written since 2023. Most teams either re-type the last ten and abandon the rest, or stay where they are. Neither is necessary.
1. Find your export
In order of preference:
- A CSV or JSON export from the tool's settings. Complete, and usually includes dates.
- Your changelog's feed, where the tool publishes one — commonly at
/feed,/rssor/atomunder your changelog address. Open it in a browser: if you see XML, that is your export. - Your repository's
CHANGELOG.md, if the public changelog grew out of it.
A feed usually holds only the most recent entries — fifty is common. If your history is longer and the tool offers a CSV, use the CSV, or import the feed and add the rest from a spreadsheet.
2. Check the dates survive
This is the part that decides whether the migration is worth doing. An import that stamps everything with today's date turns four years of shipping into one enormous day, and the timeline that made your changelog persuasive is gone.
Before importing anywhere, confirm two things:
- Entries keep their original publish dates.
- The tool will show you a preview of what it is about to write.
3. Turn off the emails, or make sure they are off
The classic migration accident: importing history and sending every subscriber 180 announcements about releases from 2023. Some tools email on every publish, and an import is a lot of publishes.
Look for an explicit statement that imported entries are not announced. In Relnotely they are marked as already announced at the moment they are written, so there is nothing to remember.
4. Import into a workspace that is still private
Do the import before you point your domain anywhere. Read the result as a stranger would:
- Does the formatting survive? Bold, lists and links should; the exact HTML of the old tool will not.
- Are the tags sensible? Most tools have more categories than the three most people use. Expect to re-tag a few.
- Are images still there? Many tools host images themselves; an import brings the text, and an image hosted on a URL you are about to stop paying for is a broken image next year. Re-upload the handful that matter.
5. Keep your addresses working
- If your changelog was on your own domain —
changelog.yourcompany.com— point the DNS at the new tool and nothing your customers have bookmarked breaks. - If it was on the old tool's domain, every link you have shared lives on a domain you are leaving. Set up whatever redirect the old tool offers, then update the links you control: the app, the docs, the footer, the onboarding emails.
- Check your in-app widget. It is usually a single script tag, and pointing it at the new tool is a one-line change, but it is also the link most teams forget.
6. Move your subscribers, carefully
Some tools let you export the list, some do not. Where you can export it, be careful what you do with it: those people agreed to hear from your changelog, and importing them somewhere they did not confirm is how sending domains get burned.
The safer path, and the one Relnotely takes deliberately, is to have the new list confirm itself: put the subscribe form on your new page, announce the move in one final message from the old tool, and let people opt in. You will lose the addresses that never really wanted it. That is not a loss.
7. Leave the old page up for a while
Do not delete the old changelog the day you move. Leave it for a month with a line at the top pointing at the new address. Search engines and bookmarks both take a while to catch up.
The order, in one list
- Export, or find your feed.
- Import into the new tool, with dates.
- Read it as a stranger.
- Re-upload the images that matter.
- Point the domain, or set redirects.
- Update the widget and the links you control.
- Invite subscribers to opt in again.
- Leave the old page up for a month.
In Relnotely, steps 1 to 3 cost nothing: reading a source and previewing exactly what would be imported is free and needs no card, so you can see your own history in the new tool before you decide anything.
Questions
- How do I export my changelog from another tool?
- Many hosted changelogs publish an RSS or Atom feed, often at your changelog address with /feed or /rss on the end; where one exists, that feed is an export. Where a tool also offers a CSV export, use it, because a feed usually holds only recent entries.
- Will my subscribers be emailed about imported entries?
- They should not be, and in Relnotely they are not — imported entries are marked as already announced. Check this before importing anywhere: sending hundreds of old announcements is the classic changelog migration accident.
- What happens to my old changelog URLs?
- If your changelog was on your own domain, point that domain at the new tool and the address keeps working. If it was on the old tool's domain, set up a redirect where the tool allows it, and update the links from your app, docs and footer.
- Can I try the import before committing to it?
- In Relnotely, yes. Reading a source and previewing every entry it would bring in is free and needs no card. You only meet billing when you publish.
Your changelog, on your own domain
One plan at $19 a month: your domain, the widget, subscriber emails, no watermark and no trackers on your readers. Writing is free — a card starts the 7-day trial when you publish.
Free tools
- Changelog Grader Score any public changelog out of 100, with the reasons.
- Release Notes Generator Turn commit messages into release notes, in your browser.
- CHANGELOG.md Validator Check a CHANGELOG.md against Keep a Changelog, line by line.