Re: Release Notes Archive Patch

On 2/28/19 2:12 PM, Magnus Hagander wrote:
> On Thu, Feb 28, 2019 at 4:15 PM Jonathan S. Katz <jkatz(at)postgresql(dot)org
> <mailto:jkatz(at)postgresql(dot)org>> wrote:
>
> On 2/28/19 7:19 AM, Magnus Hagander wrote:

> > Well, for "previous" you wouldn't need SQL :) But yes, you'd need
> a "do
> > we have release notes for the next version" in there. But you only
> need
> > those on the one-page views, so it's really not that ba
> >
> > I think it's worth it, it's definitely something *I* use a lot in the
> > old interface.
>
> I'll look into adding it then.

Added. Yay window functions :) It adds a bit more complexity to the
query (see below), but it lets people browse more easily, so yay.

>
> >
> > (And as a minor note, for the query, I don't think adding major/minor
> > versions in the WHERE clause is enough to make it fast. You need
> to push
> > it down into the actual filename in the innermost where-clause, to
> make
> > sure we get an index scan. Shouldn't be too hard)
>
> Yeah...it kind of makes constructing the query a bit uglier, which is
> why I avoided it. I'm happy to do it, but I think that given a) it's not
> a lot of rows and b) it's going to be behind varnish most of the time
> anyway that I'm not too concerned.
>
> As a compromise, I can come up with a version that does this, and we can
> decide what to do from there.
>
>
> :) Sounds like a plan.

...so if we want to keep it to one query + support lead and lag, this
does not work out. Additionally, if we try to look it up over a major
version, we end up losing out on all of the legacy release notes from
9.3 & older. It also gets complicated when you deal with release notes
for versions of documentation we don't have loaded (e.g. 6.1.x).

However, we can at least limit the search to all release notes that were
loaded from 9.3 and newer, as 9.3 will contain all of the historical
release notes.

If we really want to use the index, we can add some magic to to check
which version we're looking up (e.g. 6.1.1) and then map it to the last
known version that had all docs (i.e. 9.3).

IMHO it's creating more trouble than its worth. The # of rows is small
(~2200, and with the 9.3 restriction ~1500), it does not grow much, and
these pages will be cached the vast majority of the time. Yes, it's wide
due to "content" but again, I'm not that concerned.

> I don't like that one either :)
>
> I prefer compating it to the rest of the site, in particular after the
> work Sarah and you put in there. And compared to that, I think it feels
> a bit off.
>
> In the end, I'll be happy to defer to your judgement, just wanted to
> make sure you had heard my comments :)

So I hopefully met somewhere in the middle on this: I brought it back
down to two pages, and had an accordion on the first page:

1. Click the major version, a list of the minor versions in that major
pop out
2. Select the minor version, you're taken to the release notes. There
are some controls to navigate to diff minor versions within that version.

I have some ideas for other UX that make it nicer to display (something
more "card" based), but in the interest of time I'd prefer we get this up.

>
> > And then we highlight the release notes of the latest version directly
> > on /docs/. 
> >
> > And maybe add a link in the "online manuals" section out on the
> > righthand side of /docs/?
>
> I was actually thinking in the release notes themselves, we add a right
> nav that shows all the minor versions for the particular major version
> of the release notes.
>
>
> Ah yeah, that could be pretty good.

This is done. Latest version attached.

I also added a new Django filter given there was some code I kept
copying-and-pasting around the minor version display formatting.

If there is nothing that's grossly flawed, I'd like to get this pushed.
The two things I want us to be happy with are a) the query and b) the
URLs, as everything else can conceivably change (well, the query can
change, but I want us to be happy with how we are generating it).

Thanks,

Jonathan