Building a Public Changelog Page From Scratch

Most changelog pages fail for structural reasons, not effort reasons. Teams ship constantly, fix bugs, and push new features every week, yet the record of that work sits in the wrong place, addresses the wrong reader, or never gets written down in a form anyone outside engineering can use. Four failure modes account for nearly all of it. The first is having no public changelog at all: a prospect evaluating the product during a trial or a sales cycle finds nothing, and whatever SEO value a steady stream of dated, keyword-rich pages might have generated never materializes. The second is locking the changelog behind a login wall, which blocks search engines from indexing it and strips away the one function a changelog can serve for someone who hasn't bought yet: proof that the product is alive. The third is treating a GitHub Releases page as the changelog, a document written for developers integrating code against an API, not for the users and buyers trying to understand what the product now does for them. The fourth is sending a "what's new" email with no public web archive behind it, so the content lives and dies in inboxes and never gets indexed or linked to.

Each of these configurations produces the same outcome: the team keeps shipping, but the page produces no compounding return. There's no organic traffic accumulating around dated, specific entries. There's no trust signal available to the evaluator reading closely before a purchase decision. No one can point to a visible record of product velocity. Prospective customers do check changelogs as part of evaluating a product, treating update frequency and substance as a proxy for whether the team behind the software is actively investing in it. A changelog that is current, specific, and frequent tells that evaluator the product is alive. A changelog that is missing, buried, or stale tells them something too, just not the thing the team wants said.

The three-layer model that separates one changelog source into three audiences

A mature changelog operation does not produce one artifact from one editorial decision. It produces three artifacts from the same underlying source, the commits and pull requests that make up the actual history of the product, and writes each one for a different reader with a different purpose in mind.

Layer 1 is the technical changelog, built for developers and contributors. It lives in a file named CHANGELOG.md at the root of the repository and follows the Keep a Changelog standard: entries grouped by release version, sorted into six categories (Added, Changed, Deprecated, Removed, Fixed, Security), dated in ISO 8601 format (YYYY-MM-DD), with an Unreleased section sitting at the top to capture in-progress work. Entries are written in the imperative mood, "Add search" rather than "Added search," matching the convention used in commit messages themselves.

Layer 2 is the public changelog, built for users and prospects. It lives at a public URL, something like yoursite.com/changelog, and is formatted for a reader who has never looked at a diff: dated entries, screenshots or GIFs, plain-language descriptions of what a user can now do that they couldn't do before.

Layer 3 is the changelog newsletter, built for distribution and retention. A weekly email summarizes the period's changes, drives adoption of features a user might otherwise never discover, and keeps opted-in users current without requiring them to remember to check the page.

What makes this model work is discipline at the source. All three layers draw from the same commits and pull requests, but each layer frames that material differently: the technical changelog cites file paths, the public changelog cites user actions, the newsletter cites user impact. The underlying change is identical in all three; what shifts is which fact about that change gets foregrounded for which reader. Layer 2, the public changelog, is where the rest of this guide spends its time, because it carries the dual burden of winning user trust and generating organic discovery that the other two layers were never designed to carry.

The structural decisions that determine whether a public changelog page compounds or stagnates

The decisions that get made at the moment a public changelog page is created, where it lives, how an entry is formatted, what gets included and what gets left out, are what decide whether that page accumulates value over years or sits static and ignored after the first few entries.

URL placement comes first because it is the hardest decision to reverse later. A subdirectory URL, such as yoursite.com/changelog, inherits the authority of the main domain and gets indexed by search engines alongside the rest of the site's content. That configuration is the only one that captures both benefits a public changelog can offer: trust signal to a human evaluator and discoverability to a search engine. A subdomain, such as changelog.yoursite.com, or a changelog hosted on a third-party platform, severs the page from the main domain's link graph and gives up the internal linking benefit that a subdirectory page would have accumulated for free. Vercel's changelog lives at vercel.com/changelog, a subdirectory configuration, and individual entries are hosted at distinct slugs beneath that same path, which keeps every entry indexed under the authority of the primary domain.

Entry format is the second decision, and it has a consistent anatomy across the pages that do this well. A date stamp needs to be prominent and either in ISO format or spelled out, so both users and search engines can judge recency at a glance. A category tag, whether a simple New/Improved/Fixed taxonomy or the fuller six-category Keep a Changelog system, lets a user scan straight to the entries that matter to them. The header should name the change in plain language, describing what the user can now do. The body copy should run one to three sentences: what changed, why it matters to the user, and what to do next. At least one visual, a screenshot, a GIF, or a short video, belongs in every entry where one is practical, because entries carrying a visual are more likely to be shared organically and are understood faster than a paragraph of prose. One or two links round out the entry, pointing to documentation, a deeper blog post, or the feature itself; a changelog entry should never try to carry the full weight of a complex explanation when a link to a dedicated page can do that work instead.

What belongs on the page is anything that changes how a user experiences, integrates with, or evaluates the product: new features, behavior changes, deprecations, user-visible bug fixes, security patches. What does not belong is purely internal work, refactoring that does not alter behavior, CI configuration changes, internal tooling updates. That material belongs in a developer or internal changelog, not on the page a prospect or an existing customer is reading to judge the product's direction.

Products that serve more than one kind of user, desktop users alongside API developers alongside mobile users, benefit from platform or category tags on each entry so a reader can filter to what applies to them. Slack maintains this kind of audience separation structurally rather than through tags on a single page: a developer changelog at docs.slack.dev/changelog covers API changes, a general updates help article is organized by month for the broader user base, and iOS and Android release notes live on their own separate pages. The lesson generalizes even where the exact mechanism differs: a product with distinct audiences should make it easy for each one to find only the changes that affect them, whether that happens through tags on one page or through dedicated pages.

Writing entries that users read instead of skip

The gap between shipping something and a user understanding what changed is a writing problem before it is anything else, and it's the single most common reason changelog entries get skipped. Most entries fail because they describe what the engineer did.

The fix is a reframe applied to every entry before it gets published: write from user action, not engineer action. "Refactored auth module" describes an internal process and means nothing to a reader outside the engineering team; "Login is now faster and session handling more reliable" describes an outcome the user will actually notice. The same discipline applies to performance claims. "Improved performance" is vague enough to be meaningless, and vague performance claims actively damage trust with technical readers who have the context to recognize an unverifiable claim when they see one. A specific, named outcome, what got faster, by how much, for which users or operations, carries weight that a generic claim cannot.

Active voice reinforces the same point mechanically. The Keep a Changelog standard specifies imperative mood for a reason: "Add full-text search" reads as a capability statement about what the product does now, while "Full-text search was added" reads as a passive report of an event that happened somewhere else, to someone else. Tone should still match the product and the brand behind it. Slack's changelog entries read like a conversation rather than a press release, professional and human at once, and they explain the reasoning behind a change rather than stopping at a description of the change itself.

Developer-facing entries carry a higher bar for precision

Developer-focused changelogs need to go further than plain language, because the people reading them will test every claim right away against their own integration. If you're writing for this audience, entries should include the version number and release date, the affected endpoint paths and HTTP methods, code examples showing behavior before and after where something changed, and a link to a migration guide wherever the change breaks existing behavior. Breaking changes need to be flagged prominently rather than buried in a paragraph where an integrator might miss them. Stripe's changelog sets a standard many developer-tool teams study for this category: its API changelog provides upgrade guidance and flags breaking changes for major releases, and separate changelogs exist for the Dashboard, the API, and the SDKs, recognizing that a Dashboard user and an API integrator need entirely different information. Not every entry on Stripe's page includes a code example or a migration guide, but the structural separation between surfaces is itself the lesson: a single undifferentiated feed cannot serve both a non-technical Dashboard user and an engineer integrating against a versioned API.

The Common Changelog variant of the Keep a Changelog standard adds a further requirement that matters most for developer-tool teams: every entry must reference its pull request or issue, creating a direct audit trail from the user-facing description back to the actual code change. For a developer audience, trust rests on verifiability, and a link back to the source closes that loop in a way plain prose cannot. Common Changelog also requires that any entry introducing a breaking change carry an explicit bold Breaking: prefix, removing the ambiguity that costs an integrator real time when a change is described vaguely enough to be missed.

What should stay off the page, in either register, is anything that needs more than a short paragraph to explain properly. If a change requires a longer walkthrough, write that walkthrough as a separate post and link to it from the entry. A wall of text inside a changelog entry buries the one piece of information the entry exists to deliver.

Real pages worth studying

The strongest public changelogs prove, in practice, the structural and editorial choices described above, not just a design exercise. Each one studied here demonstrates a specific decision.

Linear is the page most people point to when they talk about public changelogs right now. Nearly every entry carries a polished screenshot or GIF that shows the change in action, and the page publishes roughly one new entry a week. What Linear's page proves is that visual-first entries paired with a real, sustained cadence generate distribution beyond the changelog page itself: entries get picked up by tech press and shared organically, and the page ranks in search for a wide range of long-tail, product-feature queries.

Vercel's changelog, at vercel.com/changelog, proves a different point: that technical depth does not require sacrificing accessibility. Entries explain the underlying concept before they move into implementation detail, and framework-specific notes for tools like Next.js or Remix let a developer find only what matters to their stack. The page's publishing rhythm is dense, with multiple entries landing on the same calendar day during active periods, which shows that a changelog does not need an elaborate design system to work. Clean organization and precise writing are enough to carry it.

Stripe proves the value of cadence discipline paired with structural separation. Changes are batched into monthly API version releases, identified by date-based version strings such as 2024-12-18.acacia, with twice-yearly major versions layered on top of that monthly rhythm. Separate changelogs exist for the Dashboard, the API, and the SDKs, and the API changelog in particular is built around upgrade guidance and breaking-change flags that stand out for major releases. The format itself functions as a trust signal: an integrator can tell, from the structure alone, that Stripe has thought carefully about what a breaking change costs its developer customers.

PostHog proves that radical transparency can work as a retention and contribution strategy for an open-source product. Its "Array" newsletter format folds changelog content together with company updates, sharing not just what changed but why the team made the decision and what it learned in the process. Some entries link to the underlying GitHub pull request through an optional metadata field, though that linkage is not a consistent feature of every entry on the page. The broader lesson still holds: an open-source team willing to show its reasoning, not just its output, can turn a changelog into a channel that builds community trust.

Loom proves a narrower but still useful point: a company willing to use its own product inside its changelog, recording a walkthrough of a new feature instead of only describing it in text, demonstrates credibility by showing the product in use.

Publishing cadence and update discipline

A well-built changelog page updated inconsistently sends a worse signal than no changelog at all, because the last entry's date is the first thing a returning user or a careful evaluator checks. A beautifully structured page with a final entry from eight months ago reads as a product that has stalled, because the structural decisions behind the page do not change how recent the last update looks.

Cadence needs to match how the team actually ships. If your team runs continuous delivery, aim for two to five entries a week; that's the minimum frequency that reads as active, ongoing development rather than sporadic activity dressed up to look busy. Teams working on a traditional release cycle should publish with every release, without exception, and treat any week or month that passes with nothing to publish as a signal to investigate the release pipeline itself, not as an acceptable gap in the record. The structural decisions covered earlier, the URL, the entry format, the audience framing, shape whether a changelog page is capable of compounding into a trust and discovery asset. Cadence shapes whether it actually does.