Re: Release note trimming: another modest proposal - Mailing list pgsql-docs

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 1/26/19 10:06 AM, Tom Lane wrote:
>> If I haven't heard objections, I'll see about making this happen
>> during the first week of Feb (after the CF closes, but before
>> it's time to do the February releases' notes).

> Thank you! I was hoping to take a crack at doing this, but I would not
> be able to do so in the above timeline. However, I should be able to review.

Attached is a diff showing what I'm thinking about, for HEAD; each
active back branch would get a similar change.  I'd also "git rm"
now-unreferenced files in relevant branches, but that'd just bulk up
the diff so I've not shown it here.

It's not quite clear to me what the policy would be for removing
back-branch links from this list when old versions drop out of support.
Should we go back and remove them in surviving back branches, or just
change HEAD?

Note that this would change our workflow for release notes a bit,
in that real editing work would happen in the back branches, rather
than them just getting copies of text from HEAD.  I don't see a big
problem there, but it's a bit different from how we've traditionally
done things.

Just for the record, this change causes the time to build HEAD's
HTML documentation to drop from ~120 sec to ~95 sec for me; the
size of the resulting html/ directory drops from 21MB to 15MB,
while the PDF output goes from 17MB to 12.2MB.  I didn't try to
measure the impact on tarball size, but it should be noticeable.

            regards, tom lane

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 5dfdf54..a03ea14 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/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">
diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml
index 4055adf..cd12e1b 100644
--- a/doc/src/sgml/release.sgml
+++ b/doc/src/sgml/release.sgml
@@ -70,27 +70,78 @@ 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.
+  When beginning a new major-release series, create a new release-N.sgml
+  file and replace the previous one with a link to the on-line documentation
+  for that branch.  Don't forget to update filelist.sgml.
 
-  The reason for splitting the release notes this way is so that appropriate
-  subsets can easily be copied into back branches.
+  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 currently-supported previous release series can be
+   found at:
+
+   <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 out-of-support release series 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>