Re: Release Notes Archive Patch

On Wed, Feb 13, 2019 at 2:13 AM Jonathan S. Katz <jkatz(at)postgresql(dot)org>
wrote:

> Hi,
>
> Attached is a proposed patch for archiving the release notes on the
> website. The patch builds the release note archive without modifying the
> schema and works with old and new releases.
>
> It works as such:
>
> - Find all release notes that have been loaded into pgweb (a process
> that occurs each release when we load the documentation)
> - Find the last modified release notes for each version. This accounts
> for the old docs, e.g. there is a copy of the 9.2.8 notes in the 9.3.9
> release, so we will render those
> - There is a list of all release notes. If you click into it, you will
> see the version specific release notes
>
> Known adjustments to be made:
>
> - The URLs on each release note page are broken. I have to figure out
> how the best way to change the relative path in the URLs that are on the
> page as it is going from the page root (/docs/release) instead of the
> site root. This _should_ be easy
> - Even with above fix, some URLs will be broken in them, i.e. references
> to other release notes
> - PostgreSQL v1 + v0: I need to relabel this for Postgres95
> - Also, some of the earlier versions do not have the proper release
> numbering (e.g. 1.03)
>
> I'm hoping we can put this out with the upcoming release, but am ok with
> doing this shortly thereafter.
>
> Comments on patch and approach welcome.
>
>
A few comments on this one:

1. It loses the "go to next minor" and "go to previous minor" links in the
previous release notes. Those should be easy enough to get back, but should
be done. E.g. if I'm on 9.6.3, I want links to 9.6.2 and 9.6.4. And we
should also use the change to make it more "explicit" and *also* have a
link to 9.6.0 on all of them amonst the links themselves.

2b. In fact, we should use this chance to create a proper set of links,
e.g. when you get to release notes for 9.6.0, it should right then and
there provide a list of all the minor releases I think -- to avoid having
to go back.

2. Links within the docs are just plain broken? E.g. the 9.6.0 release
notes link to /docs/release/9.6.0/app-pg-dumpall.html which clearly doesn't
exist. IIRC we discussed something around this, but it seems to have never
made it into the patches? (It is listed in your known adjustments to be
made above, but I could also not find a newer patch?)

3. That SQL query really needs some documentation, because it takes quite a
bit of reading to figure out what it really means. And while it works on my
dev install, it fails when i test-ran it on the current database with the
error "ERROR: invalid input syntax for type numeric: "prior". Most likely
it comes from there being a file called release-prior.html in versions
9.4-11.0 now.

It should also be reviewed for the fact that you are pulling back *all* the
documentation including *all* the contents in order to render a list of
versions...That gets annoyingly expensive when you actually have the full
set of documentation.

4. The "jump to..." list should probably be split between supported and
unsupported versions, to keep it a bit less.

5. In general, there's a huge amount of numbers on the index page. I'm not
sure what's a good way to format it better, I normally leave that to you :)
But the page is not very friendly at this point with the massive list of
numbers you have to scroll through.

//Magnus