Release note trimming: another modest proposal

On 5 August 2018 at 23:57, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Anyway, I'd like to propose a compromise position that I don't think
has been discussed before: let's drop release notes for branches
that were already EOL when a given branch was released.

WFM. +1

Regards,
Dean

On Aug 5, 2018, at 6:57 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

We've been around on this before, I know, but I got annoyed about it
again while waiting around for test builds of the back-branch
documentation. I think that we need some policy about maintaining
back-branch release notes that's not "keep everything, forever".
The release notes are becoming an ever-larger fraction of the docs,
and that's not good for documentation maintenance or for download
bandwidth. As an example, looking at the US-letter PDF version of
the v10 docs, as things stand today:

Total page count: 3550
Pages in release notes for 10.x: 41 (1%)
Pages in release notes for older branches: 898 (25%)
Pages in release notes for pre-9.2 branches: 546 (15%)

I've not measured directly, but it's a reasonable assumption that if
we dropped all the back-branch release notes the documentation build
time would drop about 25%, whichever format you were building.

I also live in fear of overrunning TeX's hard-wired limits, in the
back branches that depend on a TeX-based PDF toolchain. We've hit
those before and been able to work around them, but I wouldn't count
on doing so again, and I sure don't want to discover that we have a
problem of that sort the day before a release deadline. Trimming the
release notes would definitely give us enough slack to not worry
about that before all those branches are EOL.

We've discussed trimming the release notes before, and people have
objected on the grounds that they like being able to access ancient
notes from time to time. I'm not unsympathetic to that issue, but
does that access point need to be our daily working documentation?

I’ll reference old release notes when researching some historical
evolution of a feature, but it’s definitely not a part of daily work.

Anyway, I'd like to propose a compromise position that I don't think
has been discussed before: let's drop release notes for branches
that were already EOL when a given branch was released. So for
example, 9.3 and before would go away from v12, due out next year.
Working backwards, we'd drop 9.1 and before from v10, giving the 15%
savings in page count that I showed above. A quick measurement says
that would also trim the size of the v10 tarball by about 4%, which
is not a lot maybe but it's noticeable across a lot of downloads.

+1. This is also a time consuming process when working the release
itself, so any time savings is great.

It seems to me that this would still provide enough historical
info for just about any ordinary interest. 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/&gt;? 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>”

Jonathan

"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/&gt;? 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.

(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.)

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.

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

regards, tom lane

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/&gt;? 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

"Jonathan S. Katz" <jkatz@postgresql.org> writes:

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.

I dunno, you think it's worth the trouble? The whole premise of this
proposal is that hardly anybody is looking at those pages. If that's
not the case, we shouldn't be doing this.

OTOH, if we can easily set up a generic redirect rule like "if
https://www.postgresql.org/docs/*/static/release-*.html
doesn't exist, then redirect to
https://www.postgresql.org/docs/old-release-notes/static/release-*.html&quot;
it might be worth doing.

regards, tom lane

On 2018-Aug-06, Tom Lane wrote:

OTOH, if we can easily set up a generic redirect rule like "if
https://www.postgresql.org/docs/*/static/release-*.html
doesn't exist, then redirect to
https://www.postgresql.org/docs/old-release-notes/static/release-*.html&quot;
it might be worth doing.

Yeah I'm pretty sure we can do that.

I'm not sure how many people rely on this, but it seems useful to keep
HTML-rendered relnotes for all versions (rather than require people to
read SGML source). I don't think we need PDFs though ...

--
�lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On Aug 6, 2018, at 11:47 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

"Jonathan S. Katz" <jkatz@postgresql.org> writes:

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.

I dunno, you think it's worth the trouble? The whole premise of this
proposal is that hardly anybody is looking at those pages. If that's
not the case, we shouldn't be doing this.

I took a look at the stats and directionally it’s incredibly low. More I get
concerned by introducing 404s that could hurt any SEO-related metrics,
but that could just be general concern vs. anything factual.

OTOH, if we can easily set up a generic redirect rule like "if
https://www.postgresql.org/docs/*/static/release-*.html
doesn't exist, then redirect to
https://www.postgresql.org/docs/old-release-notes/static/release-*.html&quot;
it might be worth doing.

And looking at how the docs are served, we could do this from pgweb,
which is fairly straightforward.

FWIW I’m thinking of something like:

`/docs/release-notes/release-X-Y(-Z)?.html`

and have them all live there. Of course the docs themselves would still
have their copy of the release notes, but we could at least have a single
repository of all the releases, which I do see on other OSS projects.

Jonathan

"Jonathan S. Katz" <jkatz@postgresql.org> writes:

FWIW I’m thinking of something like:

`/docs/release-notes/release-X-Y(-Z)?.html`

and have them all live there. Of course the docs themselves would still
have their copy of the release notes, but we could at least have a single
repository of all the releases, which I do see on other OSS projects.

I'm imagining this being a repo of only the obsolete branches' release
notes, not the active ones. Otherwise we are talking about maintaining
two copies of active release note files (because of the xref problem).
I personally will flat out refuse to do that; the overhead of maintaining
the relnotes is high enough already.

Maybe you could make the website look like that without any manual effort
using a reverse redirection rule (redirecting from this new area back
into the standard docs, for pages belonging to active branches). But that
seems pretty confusing, and prone to redirection loops if we also have the
other thing.

regards, tom lane

On Aug 6, 2018, at 12:55 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

"Jonathan S. Katz" <jkatz@postgresql.org> writes:

FWIW I’m thinking of something like:

`/docs/release-notes/release-X-Y(-Z)?.html`

and have them all live there. Of course the docs themselves would still
have their copy of the release notes, but we could at least have a single
repository of all the releases, which I do see on other OSS projects.

I'm imagining this being a repo of only the obsolete branches' release
notes, not the active ones. Otherwise we are talking about maintaining
two copies of active release note files (because of the xref problem).
I personally will flat out refuse to do that; the overhead of maintaining
the relnotes is high enough already.

Well I want to make this easier, not harder. Thinking about the process of
maintaining all, no matter what, I see making it more complicated for someone,
so I will drop that for now.

Maybe you could make the website look like that without any manual effort
using a reverse redirection rule (redirecting from this new area back
into the standard docs, for pages belonging to active branches). But that
seems pretty confusing, and prone to redirection loops if we also have the
other thing.

Agreed.

So perhaps `/docs/archive/release-notes/release-X-Y-(-Z)?.html` will be where
they live.

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.

Jonathan

On Aug 6, 2018, at 1:22 PM, Jonathan S. Katz <jkatz@postgresql.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.

Thoughts?

Jonathan

On Aug 6, 2018, at 2:05 PM, Jonathan S. Katz <jkatz@postgresql.org> wrote:

On Aug 6, 2018, at 1:22 PM, Jonathan S. Katz <jkatz@postgresql.org <mailto:jkatz@postgresql.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

"Jonathan S. Katz" <jkatz@postgresql.org> writes:

On Aug 6, 2018, at 2:05 PM, Jonathan S. Katz <jkatz@postgresql.org> wrote:

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.

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.

Hm, so the only objection I can think of is that this results in the old
release notes only being available on the website; there's no other way
to access them, short of digging around in the git repo. But maybe that's
enough. It's certainly attractive that this doesn't seem like it'd entail
any manual effort once it's set up initially.

regards, tom lane

I wrote:

Hm, so the only objection I can think of is that this results in the old
release notes only being available on the website; there's no other way
to access them, short of digging around in the git repo. But maybe that's
enough.

Actually, a concrete reason why that might not be good is that it results
in having a single point of failure: once we remove branch N's relnotes
from the active branches, the only copy of that data is the one in the
archive table the docload script is filling. Given, say, a bug in the
docload script that causes it to overwrite the wrong table entries,
can we recover?

This doesn't seem insoluble, but it might mean a bit more work to do
to ensure we can revert back to an earlier version of that table.

regards, tom lane

On Aug 6, 2018, at 3:27 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

I wrote:

Hm, so the only objection I can think of is that this results in the old
release notes only being available on the website; there's no other way
to access them, short of digging around in the git repo. But maybe that's
enough.

Actually, a concrete reason why that might not be good is that it results
in having a single point of failure: once we remove branch N's relnotes
from the active branches, the only copy of that data is the one in the
archive table the docload script is filling. Given, say, a bug in the
docload script that causes it to overwrite the wrong table entries,
can we recover?

Well, the release notes are still in the git history as well as the tarballs.
One could always pull an older tarball of PostgreSQL with the full
release.sgml and load from there.

Jonathan

"Jonathan S. Katz" <jkatz@postgresql.org> writes:

On Aug 6, 2018, at 3:27 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Actually, a concrete reason why that might not be good is that it results
in having a single point of failure: once we remove branch N's relnotes
from the active branches, the only copy of that data is the one in the
archive table the docload script is filling. Given, say, a bug in the
docload script that causes it to overwrite the wrong table entries,
can we recover?

Well, the release notes are still in the git history as well as the tarballs.
One could always pull an older tarball of PostgreSQL with the full
release.sgml and load from there.

True ... as long as those older tarballs represent data that our current
workflow can process. For instance, if we did another documentation
format change (from XML to something else), the older tarballs would
perhaps no longer be useful for this purpose.

On the other hand, it's hard to believe that we'd make such a conversion
without tools to help. So probably if the situation came up, we could
cobble together something that would allow ingesting the old format.

regards, tom lane

On Aug 6, 2018, at 3:37 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

"Jonathan S. Katz" <jkatz@postgresql.org> writes:

On Aug 6, 2018, at 3:27 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Actually, a concrete reason why that might not be good is that it results
in having a single point of failure: once we remove branch N's relnotes
from the active branches, the only copy of that data is the one in the
archive table the docload script is filling. Given, say, a bug in the
docload script that causes it to overwrite the wrong table entries,
can we recover?

Well, the release notes are still in the git history as well as the tarballs.
One could always pull an older tarball of PostgreSQL with the full
release.sgml and load from there.

True ... as long as those older tarballs represent data that our current
workflow can process. For instance, if we did another documentation
format change (from XML to something else), the older tarballs would
perhaps no longer be useful for this purpose.

On the other hand, it's hard to believe that we'd make such a conversion
without tools to help. So probably if the situation came up, we could
cobble together something that would allow ingesting the old format.

Attached is a (rough) working copy of the patch to pgweb. It can:

- Extract the release notes from the docload and puts them into their
own table
- Display the release notes via pgweb akin to earlier screenshots

It needs:

- The notes actually exposed in the navigation tree
- Review how some of the xrefs are translated (esp. non-release ones)
- Dependency on all major versions being cataloged in our “Version”
table on pgweb, which currently we do not do
- Magnus review, as to do this I introduced a new Python dependency

I was able to successfully load all of the release notes from the 10.4
tarball and spot checked view several different major/minor version
combinations.

It’s not near production ready, but wanted to demonstrate that it would
not be too hard to get this done.

Jonathan

On Mon, Aug 06, 2018 at 08:14:23AM +0100, Dean Rasheed wrote:

On 5 August 2018 at 23:57, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Anyway, I'd like to propose a compromise position that I don't think
has been discussed before: let's drop release notes for branches
that were already EOL when a given branch was released.

WFM. +1

+1.
--
Michael

On Mon, Aug 6, 2018, 05:57 Tom Lane <tgl@sss.pgh.pa.us> wrote:

We've been around on this before, I know, but I got annoyed about it
again while waiting around for test builds of the back-branch
documentation. I think that we need some policy about maintaining
back-branch release notes that's not "keep everything, forever".
The release notes are becoming an ever-larger fraction of the docs,
and that's not good for documentation maintenance or for download
bandwidth. As an example, looking at the US-letter PDF version of
the v10 docs, as things stand today:

Total page count: 3550
Pages in release notes for 10.x: 41 (1%)
Pages in release notes for older branches: 898 (25%)
Pages in release notes for pre-9.2 branches: 546 (15%)

I've not measured directly, but it's a reasonable assumption that if
we dropped all the back-branch release notes the documentation build
time would drop about 25%, whichever format you were building.

I also live in fear of overrunning TeX's hard-wired limits, in the
back branches that depend on a TeX-based PDF toolchain. We've hit
those before and been able to work around them, but I wouldn't count
on doing so again, and I sure don't want to discover that we have a
problem of that sort the day before a release deadline. Trimming the
release notes would definitely give us enough slack to not worry
about that before all those branches are EOL.

We've discussed trimming the release notes before, and people have
objected on the grounds that they like being able to access ancient
notes from time to time. I'm not unsympathetic to that issue, but
does that access point need to be our daily working documentation?

Anyway, I'd like to propose a compromise position that I don't think
has been discussed before: let's drop release notes for branches
that were already EOL when a given branch was released. So for
example, 9.3 and before would go away from v12, due out next year.
Working backwards, we'd drop 9.1 and before from v10, giving the 15%
savings in page count that I showed above. A quick measurement says
that would also trim the size of the v10 tarball by about 4%, which
is not a lot maybe but it's noticeable across a lot of downloads.

It seems to me that this would still provide enough historical
info for just about any ordinary interest. 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.

Works for me. Especially with a release note archive available somewhere.

On Wed, Aug 8, 2018 at 09:53:42PM +0700, Chris Travers wrote:

It seems to me that this would still provide enough historical
info for just about any ordinary interest.� 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.

Works for me.� Especially with a release note archive available somewhere.

Works for me, though, is there no interest in keeping the SGML files in
the git tree and just not building them as docs?

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +