Re: Release note trimming: another modest proposal

> On Aug 6, 2018, at 11:09 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> "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.
>
>> 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 “If you would like to reference release
>> notes for earlier versions, please visit <URL>”
>
> Yeah, that should certainly be part of it.  The questions I have are
>
> (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’re building “pointers” to the official releases notes as opposed
to having to build them every single time.

Though thinking on this further, we’d probably want to maintain the URLs
that have been generated through the years so they don’t 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’d 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’m for
it.

Jonathan