From 48bfd3770f28b9619152ddb9318dc45c4a2e95ce Mon Sep 17 00:00:00 2001
From: Faisal Ahammad <faisalahammad24@gmail.com>
Date: Sat, 15 Aug 2026 01:11:37 +0600
Subject: [PATCH 1/2] docs: clarify changelog is maintained by hand, not
 autogenerated

The Changelog section of the release guide described the entry format but
never said the changelog is written by hand and is not produced by an
automated tool. Add a short note stating that the changelog lives in
readme.txt, is maintained by a maintainer before each release, and that
the milestone workflow only gathers merged PRs, it does not write the
changelog text.

Closes #497
---
 docs/contributing/releases.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/contributing/releases.md b/docs/contributing/releases.md
index f1ce2696..61bce44f 100644
--- a/docs/contributing/releases.md
+++ b/docs/contributing/releases.md
@@ -21,7 +21,7 @@ Using SVN for WordPress.org plugin releases is covered in more detail in <https:
 
 ## Changelog
 
-Before running the `prepare-release` script (see below), ensure the changelog entry for the new version exists in `readme.txt`:
+The changelog is maintained by hand. It is a section in `readme.txt`, not a separate `CHANGELOG.md` file, and there is no automated tool that generates it. A maintainer writes the entry for each new version before running the `prepare-release` script (see below). Entries group changes under categories such as `Feature:` and `Fix:`:
 
 ```md
 == Changelog ==
@@ -31,6 +31,8 @@ Before running the `prepare-release` script (see below), ensure the changelog en
 * Fix: Description of bug fix
 ```
 
+The milestone automation described below only assigns merged pull requests to the next release milestone, which makes it easier to gather changes when writing release notes. It does not produce the changelog text. Generating the changelog automatically is a separate open project.
+
 ## Configure the Next Milestone
 
 Merged pull requests targeting `trunk` are automatically assigned to the milestone named by the `NEXT_MILESTONE` GitHub Actions repository variable. Pull requests that already have a milestone keep it.

From e8d4c06595fb368aed553e8bd5e21728cbf36cef Mon Sep 17 00:00:00 2001
From: Faisal Ahammad <faisalahammad24@gmail.com>
Date: Fri, 23 Oct 2026 21:39:15 +0600
Subject: [PATCH 2/2] docs: widen changelog categories, fix example

- List categories as open examples: Security, Features, Fixes,
  Enhancements. Maintainers pick what fits the release.
- Update the example block to match the real readme.txt format:
  release date line, italic category headings, and dash bullets.

Addresses PR feedback.

Refs #536
---
 docs/contributing/releases.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/contributing/releases.md b/docs/contributing/releases.md
index 61bce44f..59ca9d23 100644
--- a/docs/contributing/releases.md
+++ b/docs/contributing/releases.md
@@ -21,14 +21,21 @@ Using SVN for WordPress.org plugin releases is covered in more detail in <https:
 
 ## Changelog
 
-The changelog is maintained by hand. It is a section in `readme.txt`, not a separate `CHANGELOG.md` file, and there is no automated tool that generates it. A maintainer writes the entry for each new version before running the `prepare-release` script (see below). Entries group changes under categories such as `Feature:` and `Fix:`:
+The changelog is maintained by hand. It is a section in `readme.txt`, not a separate `CHANGELOG.md` file, and there is no automated tool that generates it. A maintainer writes the entry for each new version before running the `prepare-release` script (see below). Entries group changes under category headings such as `*Security*`, `*Features*`, `*Fixes*`, and `*Enhancements*`. Use the categories that fit the release:
 
 ```md
 == Changelog ==
 
 = X.Y.Z =
-* Feature: Description of new feature
-* Fix: Description of bug fix
+*Release Date 1st January 2026*
+
+*Security*
+
+- Description of security fix
+
+*Fixes*
+
+- Description of bug fix
 ```
 
 The milestone automation described below only assigns merged pull requests to the next release milestone, which makes it easier to gather changes when writing release notes. It does not produce the changelog text. Generating the changelog automatically is a separate open project.