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 <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1fmhY1-0001Le-Mc
	for pgsql-docs@arkaria.postgresql.org; Mon, 06 Aug 2018 15:35:53 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.89)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1fmhXz-0005NL-8R
	for pgsql-docs@arkaria.postgresql.org; Mon, 06 Aug 2018 15:35:51 +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 <jkatz@postgresql.org>)
	id 1fmhXz-0005NE-2e
	for pgsql-docs@lists.postgresql.org; Mon, 06 Aug 2018 15:35:51 +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 <jkatz@postgresql.org>)
	id 1fmhXv-0005bV-CV
	for pgsql-docs@lists.postgresql.org; Mon, 06 Aug 2018 15:35:50 +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 <jkatz@postgresql.org>)
	id 1fmhXr-0000hA-Qj; Mon, 06 Aug 2018 15:35:47 +0000
From: "Jonathan S. Katz" <jkatz@postgresql.org>
Message-Id: <04F6EF85-C7B7-42F3-84BC-D5670C9D77E1@postgresql.org>
Content-Type: multipart/signed;
 boundary="Apple-Mail=_7C4B43E9-4EED-4DC2-B2A9-842EF68BA05C";
 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 11:35:41 -0400
In-Reply-To: <18020.1533568149@sss.pgh.pa.us>
Cc: pgsql-docs@lists.postgresql.org
To: Tom Lane <tgl@sss.pgh.pa.us>
References: <19252.1533509841@sss.pgh.pa.us>
 <37D00E58-A0F0-42E4-83F1-A124A282575D@postgresql.org>
 <18020.1533568149@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: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Precedence: bulk


--Apple-Mail=_7C4B43E9-4EED-4DC2-B2A9-842EF68BA05C
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=utf-8


> On Aug 6, 2018, at 11:09 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>=20
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>>> On Aug 5, 2018, at 6:57 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>> ...  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.
>=20
>> Why not www.postgresql.org <http://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
>=20
> Yeah, that should certainly be part of it.  The questions I have are
>=20
> (1) Is it sufficient to have that info on the website?  People who =
want
> it locally can always fall back on searching the development git repo,
> but it'd be less convenient perhaps.

Skimming some other OSS projects and it seems to be all over the board.
Some have a webpage covering releases, some have nicer formatted
documentation with a release section, some just link to the CHANGELOG
in a repo.

We could do something like:

- Host release notes on .org
- Have a reference in the official release notes to the page on the =
website
that houses the historical notes.

That way we=E2=80=99re building =E2=80=9Cpointers=E2=80=9D to the =
official releases notes as opposed
to having to build them every single time.

Though thinking on this further, we=E2=80=99d probably want to maintain =
the URLs
that have been generated through the years so they don=E2=80=99t all 404 =
at once.
That would require having the appropriate URL rules written out either =
in
pgweb itself or at the web server level.

> (2) How would we maintain that exactly?  It's not, for instance, =
possible
> to build the release notes as a standalone document right now.  =
(Bruce's
> eagerness to provide xrefs for just about everything is the main =
stumbling
> block, though there might be others.)

Well, as long as we are still housing the docs and those references are =
still
alive, it should be ok.

> The process I'm vaguely imagining is that when a release branch is =
EOL'd,
> before removing its release-NN.sgml file from the HEAD branch, we copy
> that file into some archive somewhere and do a one-time edit to make =
it
> buildable as part of a standalone release-notes document.  Maybe the
> "archive" contains a makefile and enough supporting stuff to build a
> document that has just the obsolete release notes, and somewhere we =
have
> a git repo for that.  Then anybody who wants local access can clone =
that
> repo (solving question 1), and we annually use it to build a new =
version
> of the old-release-notes document to put on the website.

Another option is we could have a script that just scrapes the data from
the already built docs and loads it into (file system, database, etc.). =
This could
become a part of the (minor/major) release process.

The biggest pain would be doing this the first time, as we=E2=80=99d =
have to get all
of the historical notes in a one-time sweep.

> This seems like a nontrivial amount of work, but maybe we can automate =
it
> to some extent.

If nontrivial work saves a lot of wasted time during the build process, =
I=E2=80=99m for
it.

Jonathan

--Apple-Mail=_7C4B43E9-4EED-4DC2-B2A9-842EF68BA05C
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/x8QSccp8cZScFAltoas0ACgkQ8QSccp8c
ZSf7jhAArHnHWsz30cHCfGuF2mehvcgB1kN5lL5zrei6AT1jWRP6p3pD29BqAUFF
62+Y7Tuouxhtciw6lNpfIG88G03mC42hH9xKzU51BzZRE7rp4MtwfLnk/4MW3VaS
311dV2i0aoeDLl0tYQZlC1BAbplRmi3QBtkp5SDuK2RduU4UNxCttvdK9oMJA1bc
iEnSfgxvR/CiSPUj7u0ZNOvpnMTlifmhcbFSNVWc0aDtEZBErcG9oWLBMl+gskUb
uvZ9xNMQVThcLFqgAgTRPuTgWicN5QxZbCh2hfaYKdxzZMPcIRvQls5lSGFT6j7E
tb5p4tsvb76Ii3EeuPdaNj1W6+KgQjoKPESwE7dl5oagfTcv05Y1tPh3sQYOkx9u
0kZJ8Oojhc+L8yuRHEX8JHQJZ4MXEJdD6BVeAtTDtPrhC6pAwgi0YuwYgBR/bzk0
NqYH0PCWiNPNm1FA+QUm84EvFZNAWoPKKdgQawcd3AW1ZyCh/Xz49GKnR6OuOv00
3uDtG+tzqe3LfxlDdG8Hy41+uDiStxOh+4qIoXDbhbj1ec/W6fgMQ5eCYVyxtziF
8Ua9wUzlUK1RQDSRGTLfPMi+cPqhBzm2DkgGjyMTJWBnAVPXhs2vDRischyrGgTQ
nozQbY0VDIn8dVPyXdFWc9/Lgvx547v3eFocIJA9tGioa1Fp/S0=
=Pqlb
-----END PGP SIGNATURE-----

--Apple-Mail=_7C4B43E9-4EED-4DC2-B2A9-842EF68BA05C--