From 8b61acfc35a005f30b50fca9d6226cb79cafb2eb Mon Sep 17 00:00:00 2001
From: Aba Tkosan <aba.tkosan@gmail.com>
Date: Fri, 5 Jun 2026 23:02:25 -0700
Subject: [PATCH] Recommend changelog section order by urgency

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.
---
 source/en/1.1.0/index.html.haml | 32 ++++++++++++++++++++------------
 1 file changed, 20 insertions(+), 12 deletions(-)

diff --git a/source/en/1.1.0/index.html.haml b/source/en/1.1.0/index.html.haml
index b4598f570..60ecc7a87 100644
--- a/source/en/1.1.0/index.html.haml
+++ b/source/en/1.1.0/index.html.haml
@@ -70,25 +70,34 @@ version: 1.1.0
   %a.anchor{ href: "#types", aria_hidden: "true" }
   %h4#types Types of changes
 
+  %p
+    Each type of change below is a section heading under a version. List sections in
+    the following order of urgency (omit empty sections):
+
   %ul
     %li
-      %code Added
-      for new features.
+      %code Security
+      for fixes to known security vulnerabilities and advisories.
+    %li
+      %code Removed
+      for now removed features.
     %li
       %code Changed
-      for changes in existing functionality.
+      for changes in existing functionality; prefix breaking changes so they stand out
+      (e.g.
+      %code BREAKING:
+      or
+      %strong BREAKING:
+      ).
     %li
       %code Deprecated
       for soon-to-be removed features.
-    %li
-      %code Removed
-      for now removed features.
     %li
       %code Fixed
-      for any bug fixes.
+      for any bug fixes unrelated to security.
     %li
-      %code Security
-      in case of vulnerabilities.
+      %code Added
+      for new features.
 
 .effort
 
@@ -146,9 +155,8 @@ version: 1.1.0
     become removals.
 
   %p
-    If you do nothing else, list deprecations, removals, and any
-    breaking changes in your changelog.
-
+    That said, if you do nothing else, list removals and breaking changes
+    in your changelog.
 
   %h4#confusing-dates
     %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }