A changelog entry should link to the place the reader goes to use the change, and to the documentation that explains it. Those two destinations cover almost every entry. What comes out is everything that exists to move the reader somewhere the writer wanted them: the roadmap, the pricing page for a change nobody has to buy, the pull request, the ticket, the marketing page for the feature the entry is already describing. A changelog converts by being useful, and each extra link makes it less so.
A changelog is read by people who already have the product, which makes it a different instrument from a landing page. Its readers are existing users checking whether something they wanted has arrived, evaluators auditing whether the product is maintained, and search engines building a record of what the product does. None of those three responds to persuasion; all three respond to specificity. An entry naming a setting, a screen and a date does more commercial work than the same entry with a call to action stapled to the bottom.
The evaluator case is the one most teams underestimate. Somebody comparing two products will often open both changelogs before opening either pricing page, because a changelog is the cheapest available evidence about whether a product is being worked on. That reader is not looking for a reason to buy; they are looking for a reason to eliminate. Six months of entries that each name a real change is the answer. Six months of entries that each end with a link to a demo booking is a different answer, and not the one intended.
A link earns its place in a changelog entry when the reader would otherwise have to go and find the same destination themselves. That is a narrow test and it excludes most candidates. The destination the change happens in — the settings page, the screen, the specific tab — passes it, because the reader's next action after reading is to go there. The documentation for the change passes it, because an entry has no room to explain configuration and a doc page does. A migration guide passes it when the change requires work.
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.
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.
Notice that every item on that list is a destination the reader was already heading towards. None of them is a place the writer wanted to send them. That is the whole distinction, and it is easier to apply than any rule about link counts, because it can be answered honestly for each candidate: would this reader have gone looking for this page in the next two minutes?
| Link | Why it looks tempting | Why it comes out |
|---|---|---|
| The pricing page | The change might drive an upgrade | Unless the feature is actually gated, it answers a question nobody asked |
| The public roadmap | It shows momentum | It replaces a shipped fact with an unshipped promise, in the one document that exists for shipped facts |
| The pull request or commit | It proves the work is real | It sends a non-technical reader somewhere they cannot read, to learn nothing they needed |
| The issue tracker ticket | It credits the requester | The ticket usually contains a year of context and no summary; thank the requester in the entry instead |
| The feature marketing page | It explains the feature at length | The entry already describes the change; the marketing page describes a different, older version of it |
| A demo booking or trial signup | It is the conversion goal | The reader already has the product, which makes it the wrong call to action for the wrong audience |
The roadmap row deserves the extra sentence. A changelog and a roadmap are opposite documents: one is a record of what happened, the other is a statement of intent, and mixing them costs the changelog the credibility that makes it worth reading. A reader who cannot tell shipped from planned in the same list will start discounting both. Keeping the two apart is the same instinct that keeps a changelog separate from release notes.
In Market4 the changelog body and the blog body are deliberately different shapes, and the difference is the argument in miniature. A changelog entry is built from six block types: heading, paragraph, list, image, link and divider. A blog post gets eleven, including table, quote, statistic and FAQ. The four a changelog does not get are exactly the four a sales page reaches for — the comparison table, the customer quote, the impressive figure and the objection-handling FAQ.
That constraint is not a limitation to route around. An entry that genuinely needs a comparison table is describing something big enough to need its own page, and the entry should link to that page rather than grow into it. An entry that wants a statistic is usually reaching for a number nobody measured, which is the same failure as an entry that leads with the team rather than the change.
A link belongs inside the sentence that made the reader want it, not in a row of buttons underneath. An inline link inherits the context of its own sentence, so the reader knows what they are getting before they click, and a link that cannot be described in the sentence it sits in is usually a link that had no reason to be there. A standalone link block is right for one case: a single, unambiguous next destination at the end of an entry, such as a migration guide the reader must open.
Anchor text follows the same rule as the entry itself: name the destination, not the action. "Export settings" tells the reader where they land. "Click here" tells them nothing and gives a search engine nothing. "Learn more" is the same problem wearing a longer coat. If an entry has three links whose anchors are all "read the docs", it has one link and two duplicates.
Most entries need one, some need two, and an entry with four is usually carrying links that serve the writer rather than the reader. Rather than counting, apply the destination test to each candidate: would this reader have gone looking for this page in the next two minutes? A link to the screen where the change takes effect passes almost always. A link to the pricing page passes only when the feature is genuinely gated behind a plan.
Only when the change is actually restricted to a plan the reader may not have. In that case the link is information, because it answers the question the entry just raised. When the feature is available to everybody, a pricing link answers a question nobody asked and signals that the changelog is a marketing surface. Readers adjust quickly to that signal, and the adjustment is to stop reading.
It is wrong in a customer-facing changelog and right in a developer-facing one, which is why the two documents should not be the same document. A public changelog is read by people who cannot evaluate a diff and do not want to, and sending them to one wastes the click. A changelog aimed at contributors, or the entries in a repository's own change file, are a different audience with a different appetite for detail.
The name of the destination, in sentence case, as a noun phrase. "Export settings", "the migration guide", "the webhooks reference" all tell a reader where they land before they commit to the click, and they give a search engine a description of the target page. Generic anchors such as "click here", "learn more" and "read the docs" carry no information, and repeating one of them three times in an entry produces three links that look identical.
Occasionally, and in one direction more than the other. A blog post that explains the reasoning behind a change is a reasonable destination from an entry that had no room for the reasoning. The reverse is more valuable: a blog post about a feature should link to the changelog entries that record how the feature evolved, because that is evidence rather than assertion. Avoid linking every entry to a post written to promote the same feature.
Cadence follows releases, not the calendar. The cost of stopping is not a missed post; it is a page whose most prominent fact becomes the date of the last entry.
A changelog migration is four decisions, not a copy and paste: where the entries live from now on, what address each one answers at, what happens to the links people already shared, and who writes the next entry.
