Doc: in each release branch, keep only that branch's own release notes.

Historically we've had each release branch include all prior branches'
notes, including minor-release changes, back to the beginning of the
project.  That's basically an O(N^2) proposition, and it was starting to
catch up with us: as of HEAD the back-branch release notes alone accounted
for nearly 30% of the documentation.  While there's certainly some value
in easy access to back-branch notes, this is getting out of hand.

Hence, switch over to the rule that each branch contains only its own
release notes.  So as to not make older notes too hard to find, each
branch will provide URLs for the immediately preceding branches'
release notes on the project website.

There might be value in providing aggregated notes across all branches
somewhere on the website, but that's a task for another day.

Discussion: https://postgr.es/m/cbd4aeb5-2d9c-8b84-e968-9e09393d4c83@postgresql.org

1 files changed, 32 insertions, 15 deletions

diff --git a/src/tools/RELEASE_CHANGES b/src/tools/RELEASE_CHANGES
index 65a1ffc83d5..aa1a3e1ee4f 100644
--- a/src/tools/RELEASE_CHANGES
+++ b/src/tools/RELEASE_CHANGES
@@ -7,7 +7,7 @@ For All Releases (major, minor, beta, RC)
 
 * Release notes
 	o run git log and, if useful, src/tools/git_changelog
-	o update doc/src/sgml/release.sgml
+	o update doc/src/sgml/release-NN.sgml in relevant branches
 	o run spellchecker on result
 	o add SGML markup
 
@@ -30,6 +30,11 @@ For Major Releases
 ==================
 (in addition to the above)
 
+Note that once the release branch has been forked off in git,
+release-note editing happens in that branch, not in HEAD.
+Updates to the rest of the documentation usually need to happen
+in both HEAD and the branch.
+
 * Release notes
 	o use src/tools/git_changelog
 	o retain the relevant commits
@@ -51,10 +56,6 @@ For Major Releases
 	o document all new features
 	o update help output from inside the programs
 	o doc/src/sgml/ref manual pages
-	o update the sizes specified for installation requirements
-	  (doc/src/sgml/installation.sgml, section "install-requirements")
-	o update the shared memory size requirement table
-	  (doc/src/sgml/runtime.sgml, section "shared-memory-parameters")
 
 * Ports
 	o update config.guess and config.sub at the start of beta
@@ -85,9 +86,14 @@ Starting a New Development Cycle
 
 * Run "src/tools/version_stamp.pl devel", then run autoconf
 
+* Create a new doc/src/sgml/release-NN.sgml file (initially just a
+  placeholder), "git rm" the previous one, and update release.sgml and
+  filelist.sgml to match.
+
 * Get the buildfarm's 'branches_of_interest.txt' file updated with the new
   branch.
 
+
 Creating Back-Branch Release Notes
 ==================================
 
@@ -96,21 +102,32 @@ Creating Back-Branch Release Notes
   branch tag and not the release date, as commits could have been done
   between branch stamping and the release date.
 
-* On the git master branch, edit and create SGML markup for the most recent
-  branch in that branch's release-N.N.sgml file.  Minor release notes
-  should include more small change details because testing is limited.
+* Remember to include any older branch commits not in the newest branch.
+  This can be accomplished by diff'ing the newest and older branch commit
+  logs and looking for lines that only appear in the older branch, e.g.:
+
+       diff commit-N.N.log commit-O.O.log | grep '^>'
+
+* On the most recent release branch (*not* in HEAD), edit and create SGML
+  markup for relevant changes in that branch's release-NN.sgml file.
+  Minor release notes should include more small change details because
+  testing is limited.
 
-* Copy this into older branches' release-N.N.sgml files, then remove
+* Copy this text into older branches' release-NN.sgml files, then remove
   items that do not apply based on commit logs for that branch.
 
-* Add any older branch commits not in the newest branch.  This can be
-  accomplished by diff'ing the newest and older branch commit logs and
-  looking for lines that only appear in the older branch, e.g.:
+* The minor release notes for the oldest active branch should always
+  include a warning about its impending EOL.  Use the same boilerplate
+  text used in previous branches.
 
-       diff commit-N.N.log commit-O.O.log | grep '^>'
 
-* Copy the appropriate release-N.N.sgml files into each back branch SGML
-  directory.
+Retiring a Branch
+=================
+
+After support is dropped for an old branch, remove the link for it
+in HEAD's doc/src/sgml/release.sgml.  If the newest back branch hasn't
+yet reached GA release, do the same there.  (Given our current development
+calendar, the latter should seldom be necessary.)