Compliance and your changelog: release notes as audit evidence

Sooner or later a document called a “change log” ends up in front of someone whose job is to distrust you: a SOC 2 auditor walking through your change-management controls, a prospect’s security team working down a vendor questionnaire, or a procurement reviewer checking whether your contract’s change-notification clause means anything. And here a confusion begins that this guide exists to untangle, because two very different artifacts share that name — and pointing the wrong one at the wrong reader makes you look either evasive or disorganized.

The short version: your customer-facing changelog is evidence of disclosure, not evidence of process. It will never satisfy a change-management control by itself, and it was never supposed to. But kept with a little discipline, it answers a whole class of compliance-adjacent questions better than any policy document can — because it is public, dated, and has years of history nobody could have fabricated the week before the audit.

Two documents, one name

When an auditor says “show me your change log,” they usually mean the internal change record: the trail proving that changes to production were authorized, reviewed, tested, and approved before they shipped. In SOC 2 terms this is CC8.1 territory; ISO 27001 calls it change management too. The evidence that satisfies it lives in your ticket tracker, your pull-request reviews, your CI runs, and your deploy logs — systems where each change carries an author, an approver, and a timestamp you cannot casually rewrite.

When a customer says “where’s your changelog,” they mean the public changelog: the human-readable stream of what changed, written for people who use the product. It proves something different — that when you change things, affected people can find out, on a page you maintain, with dates attached.

The failure mode is trying to make one document do both jobs. Stuff the public changelog with ticket IDs, reviewers, and rollback plans and you have leaked your internal process to the internet while boring your users (and you still will not pass the audit, because a self-published web page proves nothing about authorization). Point users at your Jira project and you have no changelog at all. Keep both, let each do its job, and let them reference each other — the same split we recommend between internal and public changelogs generally.

What the public changelog actually proves

Three situations where a disciplined public changelog is the strongest answer you have:

  • The vendor questionnaire. Nearly every security review asks some form of “How do you communicate product and API changes to customers?” A paragraph of promises is the weak answer. A URL with three years of dated entries, a security tag, feeds to subscribe to, and a published deprecation policy is the strong one — it shows the process exists by showing its output.
  • The contract clause. Enterprise agreements often include change-notification language: material changes announced N days in advance, security fixes disclosed, deprecations given a migration window. Your changelog is the receipt. When a customer claims they were never told, the dated entry with a breaking-change announcement sixty days before the change is the difference between an apology and an escalation.
  • The audit walkthrough. Auditors sample changes and trace them end-to-end. The internal record proves each change was approved; the public entry proves affected parties were told. For customer-impacting changes, “communicated via our public changelog, entry linked from the ticket” closes a loop that would otherwise take a meeting to explain.

What makes a changelog evidence-grade

A changelog that can serve as a receipt needs properties a marketing page does not:

  • Append-only history. The value of the record is that it was written at the time, not assembled later. Entries get added; old entries do not quietly change or disappear. An unbroken multi-year history is the one thing you cannot backfill — which is exactly why it is convincing (and why starting one today beats planning a perfect one).
  • Real dates. Every entry dated, unambiguously (ISO 8601 in the feeds), matching when the change actually reached users — not when someone got around to writing it up.
  • Stable permalinks. A reviewer citing your announcement needs a URL that will resolve in five years. Permalinks make entries citable in tickets, contracts, and audit workpapers; screenshots and chat messages do not resolve.
  • Tags as classification. A filterable security or breaking tag turns “show me every security fix you disclosed last year” from an afternoon of scrolling into one link.
  • An exportable copy. Evidence collection wants files. A changelog you can export as plain markdown drops into an evidence folder as-is, and doubles as your own backup.
  • Machine-readable feeds. Compliance-automation platforms and customers’ own vendor-monitoring tools increasingly poll vendors for changes. RSS and JSON feeds mean their tooling collects your notifications without anyone asking you for anything.

The silent-edit problem

The fastest way to destroy the evidentiary value of a changelog is to edit it after the fact. A record that can be quietly rewritten proves nothing — and a reviewer who catches one rewritten entry (the Wayback Machine makes this trivial) will distrust all of them.

The working norms are simple. Typo and formatting fixes are fine. Anything that changes what the entry claims — scope, dates, affected versions — gets an explicit correction: an “Updated:” line inside the entry, or a new entry linking back, the same two-pass pattern used in hotfix communication. Entries never get deleted because they became embarrassing. And history survives identity changes — a rebrand or domain move that resets the changelog to zero reads as having something to hide, and breaks every permalink anyone cited.

Answering the questionnaire

A concrete answer to the change-communication question, ready to adapt:

How do you communicate product changes to customers?

All user-facing changes are announced on our public changelog
(<url>), which provides dated, permanent entries with RSS and
JSON feeds for subscription. Breaking changes and deprecations
are tagged, announced in advance per our deprecation policy
(<url>), and security fixes are flagged at release per our
disclosure process (<url>). Changelog history is append-only;
corrections are published as explicit updates.

Every claim in that paragraph is checkable by clicking, which is what makes it a good answer. If one of the links does not exist yet, that is your to-do list.

Where the internal change record fits

None of the above replaces the change-management evidence auditors actually sample: tickets showing authorization, reviewed pull requests, test runs, deploy logs with timestamps. Those live in systems of record with access controls, and a changelog tool is not one.

But an internal changelog — a private stream your pipeline posts to at deploy time — earns its place in an audit anyway, as an evidence locator: one chronological, human-readable timeline of what shipped when, with each entry pointing at the ticket and release behind it. When the auditor picks a sample week, you scroll one page instead of reconstructing the week from four systems. It makes walkthroughs faster; it does not make controls exist.

Anti-patterns

  • Presenting the marketing changelog as your change-management system. It cannot prove authorization or review, and offering it as if it could signals you do not know what the control is for.
  • Backdating entries before an audit. Evidence prepared for the audit reads worse than a gap honestly explained — and creation dates have a way of surfacing.
  • Leaking the internal record into the public page. Ticket IDs, infrastructure names, reviewer handles, and rollback details are process disclosure your users do not need and your security team will not thank you for.
  • “Bug fixes and improvements” during a notification window. If a contract obliges you to announce material changes, vague entries during that period are a compliance gap wearing a casual outfit.
  • Screenshot archives instead of permalinks. A folder of PNGs of your own website is weaker evidence than the website — undated, uncitable, and obviously curated.
  • Resetting history at a rebrand or tool migration. Import the old entries, keep the dates, redirect the old URLs. The history is the asset; do not leave it in the old tool.

How this maps to Wakelog

Honestly first: Wakelog is not a change-management system and not a compliance platform. There are no approval workflows, no access-controlled evidence vault, no auditor seats. What it gives you is the disclosure layer done right: dated entries with stable permalinks, security and breaking tags with filterable public views, append-only-friendly editing (the public page shows publish dates, and corrections-as-new-entries is a workflow, not a feature you must buy), a one-URL changelog.md export for evidence folders, RSS and JSON feeds for anyone’s monitoring tooling, unlisted projects for the internal deploy timeline, and an API your CI can post to so the record is written when the change ships — not the night before the audit.

Give your disclosures a permanent home   Next: internal changelogs →

Related guides

Last updated 2026-07-28 · All guides