From: Joe Orton <jorton@apache.org>
Date: Fri, 17 Jul 2026 08:19:47 +0000 (+0000)
Subject: Record all(?) the conventions on how to write CHANGES entries
X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=0b645f2c107c352b967b5b7d017283f5a3819308;p=thirdparty%2Fapache%2Fhttpd.git

Record all(?) the conventions on how to write CHANGES entries
here, tweak some existing text for clarity, reflow for
line length limits and use markdown-ish formatting.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1936237 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/README.CHANGES b/README.CHANGES
index 26f8c26197..9b1c972b22 100644
--- a/README.CHANGES
+++ b/README.CHANGES
@@ -1,19 +1,49 @@
-Changes can be documented in two ways now: Either by directly editing the
-CHANGES file like it was done until now or by storing each entry for the
-CHANGES file correctly formated in a separate file in the changes-entries
+
+# Documenting User-Visible Changes
+
+User-visible changes can be documented in two ways: either by directly
+editing the CHANGES file, or by storing each entry for the CHANGES
+file correctly formatted in a separate file in the changes-entries
 directory.
 
-The benefit of the single file per change approach is that it eases backporting
-the CHANGES entry to a stable branch as it avoids the frequent merge conflicts
-as changes are merged in different orders or not at all in the stable branch.
+This covers any developer-visible changes such as a new module API,
+but e.g. code cleanups which don't have any externally-visible effect
+do not need to be documented in CHANGES.
+
+Changes should be documented by creating a file in changes-entries/
+with the .txt suffix, using the following template:
+
+```
+  *) mod_foo: Fix bug in blah blah.
+     PR <Bugzilla Number>.  [Name of Person <address example.com>,
+     Other Person <another example.com>, ...]
+```
+
+Changes to server/*.[ch] use a "core:" prefix rather than "mod_foo:".
+
+The description should be as concise as possible, a maximum of three
+lines but ideally one or two. The credit for the change goes to the
+original patch author(s) and will usually match the "Submitted by: "
+tag in the commit message. For current committers, use only the
+name and not the e-mail address in the credit. Replace "@" in any
+e-mail addresses with a space to prevent address harvesting.
+
+Use a Bugzilla bug number in the PR reference.
+
+# Generating CHANGES from changes-entries/*.txt
+
+The benefit of the single file per change approach is that it eases
+backporting the CHANGES entry to a stable branch as it avoids the
+frequent merge conflicts as changes are merged in different orders or
+not at all in the stable branch.
 
-In order to keep the current CHANGES file for the users as is there is a new
+In order to keep the current CHANGES file for the users as-is, there is a new
 make target called 'update-changes'. It merges all change files in the
 changes-entries directory to the top of the CHANGES file and removes them
 afterwards.
 
-This make target can be seen in a similar way as the scripts to update the
-documentation files from its xml sources. It can be executed immediately
-after the new file in the changes-entries directory has been created / merged
-and committed or it can be executed later. It should be executed at least before
-a release gets tagged.
+This make target can be seen in a similar way as the scripts to update
+the documentation files from the XML sources. It can be executed
+immediately after the new file in the changes-entries directory has
+been created / merged and committed or it can be executed later. It
+should be executed at least before a release gets tagged.