Re: Release note trimming: another modest proposal

> On Aug 6, 2018, at 2:05 PM, Jonathan S. Katz <jkatz(at)postgresql(dot)org> wrote:
>
>
>> On Aug 6, 2018, at 1:22 PM, Jonathan S. Katz <jkatz(at)postgresql(dot)org <mailto:jkatz(at)postgresql(dot)org>> wrote:
>> I can make a quick prototype of this on pgweb just to see how easy it is to get
>> the release notes up in it. Basically, once the archived ones are in pgweb, we
>> would not need to have to build them anymore.
>
> Attached is a screenshot of something real quick I drew up. I was able to
> generate these notes from what was already loaded in via “docload” (which
> is what happens in every release).
>
> I did manually edit the xref’s in order to have them appear more cleanly, but
> I should be able to script the process.
>
> To quote you earlier, yes there is a bit of nontrivial work here, but I do think
> we have most of the tools in place to do this. What I am thinking is the
> following:
>
> 1. Add to the “docload” script to segment out the release notes and store
> them in a separate table. Perform an “upsert” (i.e. check for an existing
> reference; if it’s there, update any content, otherwise insert).
>
> 2. Perform any modifications to the content (i.e. there’s some HTML I
> explicitly removed from the generated docs).
>
> 3. Display the archived docs on the page.
>
> That way in future docloads, if there are missing release notes, the script
> would be ok as it would not remove any release notes.
>
> This strategy *should* also work with displaying current release notes on the
> site, as it’s basically following what docload currently does, if we wanted to
> go down this patch.
>
> Once we run this for the first time with the collection of *all* release notes,
> we could then trim down release.sgml et al. And thus as far as I can tell, you
> would not have to modify anything in the doc build process.

OK, I’ve codified Step #2 from the above, which in turn performs Step #3.

The script reads in the releases notes that are loaded in via docload, updates
the xrefs to point to other releases notes in the archive, updates the doc URLs
to point at the equivalent docs in “current,” and performs some general
cleanup on the page.

Attached is another screenshot of the end result.

To proceed, I would want to ensure we feel good about this direction. I will
also need to discuss with Magnus about how we would want to store this
in pgweb itself. And of course, test it across all the different release notes
to ensure it works.

Jonathan