Received: from malur.postgresql.org ([2a02:16a8:dc51::56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.89) (envelope-from ) id 1fmgha-0006jX-I4 for pgsql-docs@arkaria.postgresql.org; Mon, 06 Aug 2018 14:41:42 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1fmghY-0007pA-Bb for pgsql-docs@arkaria.postgresql.org; Mon, 06 Aug 2018 14:41:40 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.89) (envelope-from ) id 1fmghY-0007p3-5h for pgsql-docs@lists.postgresql.org; Mon, 06 Aug 2018 14:41:40 +0000 Received: from meldrar.postgresql.org ([2a02:c0:301:0:ffff::31]) by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.89) (envelope-from ) id 1fmghU-0004JY-RG for pgsql-docs@lists.postgresql.org; Mon, 06 Aug 2018 14:41:39 +0000 Received: from [144.121.72.194] (helo=[172.16.7.107]) by meldrar.postgresql.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.89) (envelope-from ) id 1fmghR-0006ex-3I; Mon, 06 Aug 2018 14:41:36 +0000 From: "Jonathan S. Katz" Message-Id: <37D00E58-A0F0-42E4-83F1-A124A282575D@postgresql.org> Content-Type: multipart/signed; boundary="Apple-Mail=_6FCA41D9-B43E-4EFF-99E0-B75B6D34A42E"; protocol="application/pgp-signature"; micalg=pgp-sha256 Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\)) Subject: Re: Release note trimming: another modest proposal Date: Mon, 6 Aug 2018 10:41:28 -0400 In-Reply-To: <19252.1533509841@sss.pgh.pa.us> Cc: pgsql-docs@lists.postgresql.org To: Tom Lane References: <19252.1533509841@sss.pgh.pa.us> X-Mailer: Apple Mail (2.3273) X-Host-Lookup-Failed: Reverse DNS lookup failed for 144.121.72.194 (failed) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --Apple-Mail=_6FCA41D9-B43E-4EFF-99E0-B75B6D34A42E Content-Type: multipart/alternative; boundary="Apple-Mail=_BA8F59B2-746E-4E1D-9F75-5485978C32B7" --Apple-Mail=_BA8F59B2-746E-4E1D-9F75-5485978C32B7 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 > On Aug 5, 2018, at 6:57 PM, Tom Lane wrote: >=20 > We've been around on this before, I know, but I got annoyed about it > again while waiting around for test builds of the back-branch > documentation. I think that we need some policy about maintaining > back-branch release notes that's not "keep everything, forever". > The release notes are becoming an ever-larger fraction of the docs, > and that's not good for documentation maintenance or for download > bandwidth. As an example, looking at the US-letter PDF version of > the v10 docs, as things stand today: >=20 > Total page count: 3550 > Pages in release notes for 10.x: 41 (1%) > Pages in release notes for older branches: 898 (25%) > Pages in release notes for pre-9.2 branches: 546 (15%) >=20 > I've not measured directly, but it's a reasonable assumption that if > we dropped all the back-branch release notes the documentation build > time would drop about 25%, whichever format you were building. >=20 > I also live in fear of overrunning TeX's hard-wired limits, in the > back branches that depend on a TeX-based PDF toolchain. We've hit > those before and been able to work around them, but I wouldn't count > on doing so again, and I sure don't want to discover that we have a > problem of that sort the day before a release deadline. Trimming the > release notes would definitely give us enough slack to not worry > about that before all those branches are EOL. >=20 > We've discussed trimming the release notes before, and people have > objected on the grounds that they like being able to access ancient > notes from time to time. I'm not unsympathetic to that issue, but > does that access point need to be our daily working documentation? I=E2=80=99ll reference old release notes when researching some = historical evolution of a feature, but it=E2=80=99s definitely not a part of daily = work. > Anyway, I'd like to propose a compromise position that I don't think > has been discussed before: let's drop release notes for branches > that were already EOL when a given branch was released. So for > example, 9.3 and before would go away from v12, due out next year. > Working backwards, we'd drop 9.1 and before from v10, giving the 15% > savings in page count that I showed above. A quick measurement says > that would also trim the size of the v10 tarball by about 4%, which > is not a lot maybe but it's noticeable across a lot of downloads. +1. This is also a time consuming process when working the release itself, so any time savings is great. > It seems to me that this would still provide enough historical > info for just about any ordinary interest. We could discuss ways > of making a complete release-note archive available somewhere, > if "go dig in the git repo" doesn't seem like an adequate answer > for that. Why not www.postgresql.org ? We could add it = as a subnav to the documentation section and just have the entire archive there. We could then update the official docs to say =E2=80=9CIf you would like to = reference release notes for earlier versions, please visit =E2=80=9D Jonathan --Apple-Mail=_BA8F59B2-746E-4E1D-9F75-5485978C32B7 Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=utf-8
On Aug 5, 2018, at 6:57 PM, Tom Lane <tgl@sss.pgh.pa.us> = wrote:

We've been around on this before, I know, but I got annoyed = about it
again while waiting around for test builds of the = back-branch
documentation.  I think that we need some = policy about maintaining
back-branch release notes that's = not "keep everything, forever".
The release notes are = becoming an ever-larger fraction of the docs,
and that's = not good for documentation maintenance or for download
bandwidth.  As an example, looking at the US-letter PDF = version of
the v10 docs, as things stand today:

Total page count: 3550
Pages in = release notes for 10.x: 41 (1%)
Pages in release notes for = older branches: 898 (25%)
Pages in release notes for = pre-9.2 branches: 546 (15%)

I've not = measured directly, but it's a reasonable assumption that if
we dropped all the back-branch release notes the = documentation build
time would drop about 25%, whichever = format you were building.

I also live in = fear of overrunning TeX's hard-wired limits, in the
back = branches that depend on a TeX-based PDF toolchain.  We've hit
those before and been able to work around them, but I = wouldn't count
on doing so again, and I sure don't want to = discover that we have a
problem of that sort the day = before a release deadline.  Trimming the
release = notes would definitely give us enough slack to not worry
about that before all those branches are EOL.
We've discussed trimming the release notes before, and = people have
objected on the grounds that they like being = able to access ancient
notes from time to time.  I'm = not unsympathetic to that issue, but
does that access = point need to be our daily working documentation?

I=E2=80= =99ll reference old release notes when researching some = historical
evolution of a feature, but it=E2=80=99s definitely = not a part of daily work.

Anyway, I'd like to propose a = compromise position that I don't think
has been discussed = before: let's drop release notes for branches
that were = already EOL when a given branch was released.  So for
example, 9.3 and before would go away from v12, due out next = year.
Working backwards, we'd drop 9.1 and before from = v10, giving the 15%
savings in page count that I showed = above.  A quick measurement says
that would also trim = the size of the v10 tarball by about 4%, which
is not a = lot maybe but it's noticeable across a lot of downloads.

+1. = This is also a time consuming process when working the = release
itself, so any time savings is great.

It seems to me that this would still provide enough = historical
info for just about any ordinary interest. =  We could discuss ways
of making a complete = release-note archive available somewhere,
if "go dig in = the git repo" doesn't seem like an adequate answer
for = that.

Why not www.postgresql.org? We = could add it as a subnav to the
documentation section and just = have the entire archive there. We could
then update the = official docs to say =E2=80=9CIf you would like to reference = release
notes for earlier versions, please visit = <URL>=E2=80=9D

Jonathan
= --Apple-Mail=_BA8F59B2-746E-4E1D-9F75-5485978C32B7-- --Apple-Mail=_6FCA41D9-B43E-4EFF-99E0-B75B6D34A42E Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=signature.asc Content-Type: application/pgp-signature; name=signature.asc Content-Description: Message signed with OpenPGP -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEE+oS2la8r95ogZD/x8QSccp8cZScFAltoXhgACgkQ8QSccp8c ZSc3XBAAqpBxgjWjNY5xX3Z+Zi/Mlvtj81ABIhqdexwDPZ5Iyj5Wu1YkuuJARhW+ jJcJlnwn+xkTEjNxQYozas3P5DmUVUAeJlpPdeay+t5deGlHid81Ti5/Zrj4g6S3 WNB5WSYYDs+swcT6PvKCzEgkYZWa6zgC9wkVrAJqrcpkF+Q/8Cz41hkiWej6WyRe ssa5bWIQ8nXZHEBrR657v4FauV/ZMgBBn9+uc60VWfT6jYySHMUuBmJNfez/LVzX 8A+B0gdH/E5DZDWCDTJ6aWHCh9XWEaEOQIUy3jUZY/SaoghCQ5n5yO1PEp/gs+6b bU4PmXqUYs2KQIrF/ukEIGFsRY8cfeXx4CuTszjdnL7qMfCPOAJ0rwwPxm2I6cLh lccuzQ3jp7Svxa7dTnxyalCbPHWX3su6d3MstArhN+zkWyqbm7MDRqU3kvGpwWJn cwOQbw09oyJ1XP1WPWi2RlfqjYywe3uLRQ3IjjcJArDFFeDFDA4B/RdiX2c1p9kj s2XCtG1TXZVbpR1OccH4+D5+8ptGZi57Ag+zrRcn88iUAokRvJBqukoGWbMJV50E dXsfWUSwmOOV6Z+oLXvjG36pBZmKQhE2fANy77oNS6k+xXytp7KJyLCL2SO1DLRK ZeDd56kfUTOEX7Z3/4Cw9Xwy1szNNQJuUfbkMvX57hGAyT6rPmc= =0Rmt -----END PGP SIGNATURE----- --Apple-Mail=_6FCA41D9-B43E-4EFF-99E0-B75B6D34A42E--