svn commit: r1936237 - httpd/httpd/trunk

Author: jorton
Date: Fri Jul 17 08:19:47 2026
New Revision: 1936237

Log:
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.

Modified:
   httpd/httpd/trunk/README.CHANGES

Modified: httpd/httpd/trunk/README.CHANGES
==============================================================================
--- httpd/httpd/trunk/README.CHANGES	Fri Jul 17 08:13:09 2026	(r1936236)
+++ httpd/httpd/trunk/README.CHANGES	Fri Jul 17 08:19:47 2026	(r1936237)
@@ -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.