Merge r1936238, r1936237 from trunk:

CI: Skip CI for README* changes at the top-level.

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/branches/2.4.x@1936240 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
index 2b262379809db34c6fe89f3e8a49d1ffbefc7954..05c9b53162210f2ff85de6b61f3fab767ee15d4d 100644 (file)
--- a/.github/workflows/linux.yml
+++ b/.github/workflows/linux.yml
@@ -7,6 +7,7 @@ on:
       - 'docs/**'
       - STATUS
       - CHANGES
+      - README*
       - '**.md'
       - changes-entries/*
     tags:
@@ -17,6 +18,7 @@ on:
       - 'docs/**'
       - STATUS
       - CHANGES
+      - README*
       - '**.md'
       - changes-entries/*
 

diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml
index 5f6a376bace21b485fcdd7b9fc96ff3c35b9b223..5922cc68a518870e5c075419fc6d20403c5e84d3 100644 (file)
--- a/.github/workflows/windows.yml
+++ b/.github/workflows/windows.yml
@@ -7,6 +7,7 @@ on:
       - 'docs/**'
       - STATUS
       - CHANGES
+      - README*
       - '**.md'
       - changes-entries/*
     tags:
@@ -17,6 +18,7 @@ on:
       - 'docs/**'
       - STATUS
       - CHANGES
+      - README*
       - '**.md'
       - changes-entries/*
 

diff --git a/README.CHANGES b/README.CHANGES
index 26f8c26197a87476ae4548d43f9ab4be3a4bf28e..9b1c972b22197496ade7c43962e9317493b4576e 100644 (file)
--- 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.