There are two people reading your API changelog. One is debugging right now and wants to know what changed since Friday. The other is in procurement, trying to decide whether your API is a dependency they will regret. The same document has to serve both.
Date, version, and what actually broke
Every entry needs a date, a version, and an honest classification. 'Improved performance' is not an entry. 'p95 on GET /v2/catalog/items fell from 190ms to 63ms after we moved the price join' is an entry, and it tells the debugging reader whether their problem is yours.
- Breaking changes first, always, with a migration path.
- Deprecations with a date, not a vague 'in a future release'.
- Additions with the endpoint and the field, so it is searchable.
Make it machine readable
Ship an RSS feed and a webhook. Integrators who care will subscribe, and the ones who care are the ones whose upgrade you want to be painless.
A changelog nobody can subscribe to is a blog post with better formatting.
Do not hide the incidents
The changelog and the status page should agree. If Tuesday was bad, say so in both places, link them, and describe what changed as a result. The procurement reader is not looking for a perfect record. They are looking for evidence that you notice.