Migrating your changelog: switching tools without losing your history

Sooner or later most teams switch changelog tools. The free tier went away, the vendor shut down, the widget got slow, you outgrew a markdown file, or you finally got tired of posting updates into something nobody can link to. The switch itself is easy — every tool has a shiny “get started” path. What the shiny path quietly skips is the part that matters: your history. A changelog that goes back years is one of the strongest trust signals a product has — the archive guide covers who actually reads old entries — and a careless migration can destroy in an afternoon what took four years to accumulate. This guide is the careful version.

What you’re actually moving

“Migrate the changelog” sounds like one job. It’s five, and they fail independently:

  • The entries — titles, bodies, tags, and above all dates. This is the easy 80%, and the only part most people plan for.
  • The permalinks. Old entry URLs are cited in support threads, closed tickets, Stack Overflow answers, dependabot PRs, and your own docs’ “Changed in…” notes (docs vs changelog). Those links don’t know you’re moving.
  • The feed subscribers. RSS and JSON feed readers are bound to a URL. Change it silently and every subscriber is gone — and none of them will notice, which is worse.
  • The embeds. The in-app “What’s new” widget, the README badge, the footer link — every place the old tool’s snippet is pasted keeps pointing at it after you leave.
  • The search equity. If your changelog pages rank for anything (they often do), the URLs carry that. Whether you can keep it depends entirely on who owns the domain — see below.

Entries move in an hour. The other four are the difference between a migration and a quiet fire.

Step zero: get your history out

Before you evaluate a single new tool, find out what the old one will give you. Work down this ladder and stop at the first rung that works:

  • A real export. Markdown or JSON with titles, bodies, and original dates. Dated markdown in roughly the Keep a Changelog shape is the lingua franca — nearly everything can ingest it.
  • A public API. No export button, but a list endpoint you can page through with a script. Half an hour of work; full fidelity.
  • The feed. RSS usually holds only the newest 20–50 entries. Fine for a young changelog, silently incomplete for an old one — check the oldest item’s date before trusting it.
  • Your own public page. Scraping your own changelog is undignified but honest. Paginate to the very end; the oldest entries are the ones worth the trouble.
  • Retyping. The floor. If you’re here, you’ve learned the real lesson of this guide early: judge every tool by its exit door. A tool with no export isn’t a home for your history, it’s a hostage-taker with a free tier. Apply that test to the tool you’re moving to, today, while you’re motivated — not in three years when it’s your turn to leave it.

Dates are the cargo

The single most common migration injury: the import runs fine, every entry arrives — and every one is stamped with the import date. Four years of shipping compressed into one Tuesday. The ledger becomes a dump; the evaluator reading backwards sees a product that apparently started existing last week; the backdating rule — original dates or nothing — is violated wholesale.

So make date fidelity the acceptance test for the new tool’s importer: import a sample, then check the oldest entry, not the newest. While you’re there, check the two subtle cases: same-day entries should keep their relative order, and dates shouldn’t drift a day from timezone handling. If the importer can’t preserve dates, the tool has already failed the migration — whatever else it does well.

The permalink problem

What happens to the old URLs depends on one question: who owns the domain they live on?

  • You own it (the changelog lived at yourapp.com/changelog or a subdomain you control): you can redirect. Build a mapping from old URL to new permalink and serve 301s — a static redirects file on most hosts. Readers, old support links, and search engines all follow you. This is the good case; it’s also the argument for putting the next changelog on a domain you control.
  • The vendor owns it (yourapp.vendortool.io): you cannot redirect, full stop. Best available: keep the old page alive as long as the vendor allows, with a final pinned entry pointing at the new home — and accept that every deep link into it will eventually die. This is lock-in’s actual bill, and it arrives at the exact moment you’re trying to leave.

Either way, fix the links you do control: your docs’ “Changed in” references, your README, your support macros, your onboarding emails. Those are your highest-value inbound links and they’re one grep away.

Feeds, widgets, and the silent losses

Nobody emails you when their feed reader starts getting 404s — subscriptions just rot. Before the old feed goes dark, publish one final entry in the old tool: “This changelog has moved — new home and feed at <url>.” It’s the only message guaranteed to reach feed subscribers, chat bridges, and anyone else consuming the old URL (machines read changelogs too, and they’re the least likely to notice a move). If the old tool lets the feed keep serving that pointer entry indefinitely, leave it there forever.

Then hunt the embeds: the widget snippet in your app, the badge in your README, the footer link, the Slack/Discord mirror. Ship the new snippet in the same release that announces the move — a “What’s new” bell that opens a dead feed is worse than no bell, because it says nothing new has shipped when plenty has.

The cutover, in order

  1. Import history into the new tool. Verify the count matches, spot-check the oldest and newest entries, confirm dates survived.
  2. Freeze the old tool. From this moment, new entries go to the new home only. Posting to both “for a while” guarantees the two histories diverge and you do this migration twice.
  3. Switch every pointer you control — docs, nav, footer, README badge, widget snippet, chat mirrors — in one pass, against the inventory from the first section.
  4. Set up redirects if you own the old domain.
  5. Post the pointer entry in the old tool (if you can) and a short meta-entry in the new one: “Same changelog, new home — history came with us.” One modest entry, not a product launch: readers care that the record survived, not which vendor lost the account.
  6. Keep the old tool read-only through a grace period — a month or two — then archive it. Deleting it on day one turns every not-yet-updated link into a 404 while the ink on the redirects is still wet.

What not to carry

Migration is also a chance to leave the right things behind. View counts and reaction tallies don’t port and don’t matter — they were signals for you, not content. Half-written drafts should be finished or dropped, not imported as cargo. Tool-specific formatting — proprietary embeds, custom blocks — should be flattened to plain markdown that will survive the next migration too.

What you should not do is rewrite history while it’s in transit. Fixing a broken link or a typo in a 2023 entry is maintenance; “tightening up” old entries to match your current voice is revisionism — the archive guide’s edit rules apply exactly as much during a migration as after one. The record’s value is that it’s the record.

Anti-patterns

  • The import-day timestamp. Every entry dated the day of migration. Years of ledger, gone in one checkbox nobody read.
  • The same-day teardown. Old tool deleted the afternoon the new one launches, before the redirects, docs links, or subscribers caught up.
  • History laundering. “While we’re migrating, let’s clean up the old entries…” — and the awkward outage admission from 2024 quietly doesn’t make the trip.
  • Solving lock-in with lock-in. Leaving a tool with no export for another tool with no export, because its import path was smooth. Import is how tools acquire you; export is how they respect you.
  • The fresh start. “Our changelog starts fresh today — old entries are over there.” A history split across two homes is half as credible in both, and the old home is one billing lapse from oblivion.
  • The bundled relaunch. New tool, new tone, new cadence, new categories, all at once — so readers can’t tell what actually changed. Move the history first; renovate later, one change at a time.

Where Wakelog fits

Wakelog is built around the exit-door test — in both directions. Coming in: paste your CHANGELOG.md, point the importer at a GitHub repo’s Releases — or give it your old tool’s RSS/Atom feed URL: Headway, LaunchNotes, AnnounceKit and most other hosted changelog tools expose one, and Wakelog will find it from your changelog page’s URL if you don’t know it. Entries arrive with their original dates preserved, same-day order intact; duplicate titles are skipped, so re-running an import is safe rather than catastrophic. You can preview the import without an account. Going out: every project serves a portable changelog.md export — one GET request, no login — that round-trips through our own importer, which is the exit-door test applied to ourselves. Honest caveats: a feed usually carries the recent tail of your history, not all of it — for the deep archive, get it to markdown first (the ladder above) and it flows in — and if your old changelog lived on a vendor’s domain, nobody, including us, can host redirects for it. The permalinks you build here live at URLs that stay yours to point wherever you go next — even away from us.

Preview your changelog on Wakelog — no signup   Next: what to do with years of old entries →

Related guides

Last updated 2026-07-30 · All guides