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

doc/src/sgml/filelist.sgml

@@ -166,22 +166,6 @@
 
 <!ENTITY release    SYSTEM "release.sgml">
 <!ENTITY release-12     SYSTEM "release-12.sgml">
-<!ENTITY release-11     SYSTEM "release-11.sgml">
-<!ENTITY release-10     SYSTEM "release-10.sgml">
-<!ENTITY release-9.6    SYSTEM "release-9.6.sgml">
-<!ENTITY release-9.5    SYSTEM "release-9.5.sgml">
-<!ENTITY release-9.4    SYSTEM "release-9.4.sgml">
-<!ENTITY release-9.3    SYSTEM "release-9.3.sgml">
-<!ENTITY release-9.2    SYSTEM "release-9.2.sgml">
-<!ENTITY release-9.1    SYSTEM "release-9.1.sgml">
-<!ENTITY release-9.0    SYSTEM "release-9.0.sgml">
-<!ENTITY release-8.4    SYSTEM "release-8.4.sgml">
-<!ENTITY release-8.3    SYSTEM "release-8.3.sgml">
-<!ENTITY release-8.2    SYSTEM "release-8.2.sgml">
-<!ENTITY release-8.1    SYSTEM "release-8.1.sgml">
-<!ENTITY release-8.0    SYSTEM "release-8.0.sgml">
-<!ENTITY release-7.4    SYSTEM "release-7.4.sgml">
-<!ENTITY release-old    SYSTEM "release-old.sgml">
 
 <!ENTITY limits     SYSTEM "limits.sgml">
 <!ENTITY acronyms   SYSTEM "acronyms.sgml">

doc/src/sgml/release-12.sgml

@@ -4,8 +4,14 @@
  <sect1 id="release-12">
   <title>Release 12</title>
 
-  <para>JIT is enabled by default in this release.  It was disabled by
-  default in PG 11, so we document is enablement here.
+  <para>
+   This is just a placeholder for now.  Actual notes will appear
+   after feature freeze.
+  </para>
+
+  <para>
+   JIT is enabled by default in this release.  It was disabled by
+   default in PG 11, so we should document its enablement here.
   </para>
 
  </sect1>

doc/src/sgml/release.sgml

@@ -70,27 +70,81 @@ For new features, add links to the documentation sections.
   </para>
 
 <!--
-  To add a new major-release series, add an entry here and in filelist.sgml.
-
-  The reason for splitting the release notes this way is so that appropriate
-  subsets can easily be copied into back branches.
+  When beginning a new major-release series, create a new release-NN.sgml
+  file, removing the previous one, and change the &-reference here.
+  Don't forget to update filelist.sgml.  Also, add a link to the on-line
+  documentation for the newly forked-off branch in the list below.
+
+  The reason for keeping each branch's release notes in a differently-named
+  file is to reduce confusion when preparing minor-release updates.
+  All the active branches have to be edited concurrently when doing that.
 -->
+
 &release-12;
-&release-11;
-&release-10;
-&release-9.6;
-&release-9.5;
-&release-9.4;
-&release-9.3;
-&release-9.2;
-&release-9.1;
-&release-9.0;
-&release-8.4;
-&release-8.3;
-&release-8.2;
-&release-8.1;
-&release-8.0;
-&release-7.4;
-&release-old;
+
+ <sect1 id="release-prior">
+  <title>Prior Releases</title>
+
+  <para>
+   Release notes for prior release branches can be found on the
+   <ulink url="https://www.postgresql.org/"><productname>PostgreSQL</productname></ulink>
+   web site.  At the time of release of version 12,
+   these were the supported prior release branches:
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      <productname>PostgreSQL</productname> 11:
+      <ulink url="https://www.postgresql.org/docs/11/release.html">
+       <literal>https://www.postgresql.org/docs/11/release.html</literal>
+      </ulink>
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <productname>PostgreSQL</productname> 10:
+      <ulink url="https://www.postgresql.org/docs/10/release.html">
+       <literal>https://www.postgresql.org/docs/10/release.html</literal>
+      </ulink>
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <productname>PostgreSQL</productname> 9.6:
+      <ulink url="https://www.postgresql.org/docs/9.6/release.html">
+       <literal>https://www.postgresql.org/docs/9.6/release.html</literal>
+      </ulink>
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <productname>PostgreSQL</productname> 9.5:
+      <ulink url="https://www.postgresql.org/docs/9.5/release.html">
+       <literal>https://www.postgresql.org/docs/9.5/release.html</literal>
+      </ulink>
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <productname>PostgreSQL</productname> 9.4:
+      <ulink url="https://www.postgresql.org/docs/9.4/release.html">
+       <literal>https://www.postgresql.org/docs/9.4/release.html</literal>
+      </ulink>
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+
+  <para>
+   Release notes for older release branches can be found at
+   <ulink url="https://www.postgresql.org/docs/manuals/archive/">
+    <literal>https://www.postgresql.org/docs/manuals/archive/</literal>
+   </ulink>
+  </para>
+ </sect1>
 
 </appendix>

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.)