An API change is not complete when a pull request merges. Builders need to know whether the change is proposed, implemented, merged, deployed, and product-proven; which behavior changed; whether action is required; and how to verify their integration. A trustworthy changelog is an operational interface, not a marketing scrapbook.
Name the delivery rung
These statements are not interchangeable:
- Proposed: a design or issue exists.
- Implemented: source exists on a branch.
- Merged: the change reached the main branch.
- Deployed: a specific environment serves the change.
- Product-proven: the customer-visible lifecycle was observed on the deployed version.
“Shipped” should not hide which rung the evidence supports.
What a useful entry contains
For a developer-facing change, record:
- Date and release identifier.
- The affected endpoint, tool, SDK, guide, or behavior.
- Previous and new contract.
- Compatibility or migration impact.
- Failure-mode differences.
- Exact verification path.
- Anything intentionally still unproven.
For example, changing a write path to return 204 should say that clients must not parse JSON and that asynchronous persistence requires a later read. “Improved memory” is not actionable.
Documentation-only releases matter
Correcting an unsupported SDK example or native-integration implication can be as important as changing code. The changelog should identify it as a docs/truth correction, not pretend the product runtime changed.
Likewise, adding a concept page for Beacon or Context Spaces does not ship those features. The entry should state that the page documents design and graduation gates.
Machine-readable surfaces must agree
Developer trust erodes when the visible changelog, OpenAPI document, SDK types, llms.txt, agents.json, examples, and integration pages describe different products. Treat them as one release set:
runtime contract
-> API reference / OpenAPI
-> SDK and examples
-> integration guides
-> changelog
-> llms.txt / agents.json
Run claims and link checks across all of them, not only the human-readable page.
A changelog can still overclaim
A commit SHA proves source state. A migration file proves intended schema. A passing local test proves the tested checkout. None alone proves production deployment or a customer outcome.
Entries should avoid invented benchmarks, universal availability, unnamed “enterprise” guarantees, and integration claims stronger than the exact adapter or custom mapping demonstrated.
The current Northsun (formerly Mnemix) changelog separates docs corrections from product behavior. For callable contracts, continue to API reference and MCP server.