Recommend changelog section order by urgency

[abatko]

Summary

Clarifies Types of changes with a recommended section order and omits-empty-sections rule. Updates Ignoring Deprecations wording to match upgrade urgency.

Problem

The spec lists six section types but not their order within a release. Example changelogs (including on keepachangelog.com) often lead with Added, so a quick skim can miss security fixes, removals, and breaking changes listed below.

Proposed order (omit empty sections)

Security → Removed → Changed → Deprecated → Fixed → Added

• Security first.
• Added last - new features are usually optional for upgrade; removals/breaking changes are not.
• Fixed scoped to non-security bugs; security items stay under Security.
• Changed: prefix breaking entries (e.g. BREAKING:) so they stand out.

Ignoring Deprecations

Reword closing line: minimum bar is removals and breaking changes; deprecations remain important for the two-step upgrade path described above.

Semver

I’m not changing the spec version in this PR. If this guidance is normative, I’d expect 2.0.0; if recommended, 1.2.0. Happy to adjust wording or target a new spec page.

Commit message

Readers skim changelogs to learn what affects them most. The spec listed change types but gave no guidance on section order, so projects often buried urgent items (security fixes, removals) below additions and minor fixes.

Introduce a recommended section order under each version, from most to least urgent: Security, Removed, Changed, Deprecated, Fixed, Added.

Clarify that Fixed is for non-security bug fixes, to distinguish it from the Security section now that everything is ordered by urgency.

Document how to mark breaking changes within Changed (e.g. BREAKING: in code or bold).

In Ignoring Deprecations, separate the ideal upgrade path (list deprecations so users can migrate in steps) from the absolute minimum for negligent maintainers. "That said, if you do nothing else" sets that floor at removals and breaking changes - what breaks today - without repeating deprecations or diluting the paragraph above.

[abatko]

@olivierlacan - just remembered about this. did you see it?

[olivierlacan]

Sorry for not responding earlier. I'm shuffling a lot of things around so this might land in 2.0.

On its face this makes a lot of sense to me.

[olivierlacan]

Thanks @abatko — your recommendation to order changelog sections by urgency is going into Keep a Changelog 2.0.

The 2.0 "Types of changes" guidance now recommends Security, Removed, Changed, Deprecated, Fixed, Added (omitting empty sections), explains the reasoning behind it, and the example changelogs were reordered to match. Because 2.0 is authored in Markdown on a restructured page, it was reimplemented there rather than merged from this branch, but the recommendation and its rationale are yours. The separate tweak to the "Ignoring Deprecations" wording is still under consideration.

Appreciate the clear write-up and the nudge to finally settle this (it also resolves #458).

---

Generated by Claude Code