Release note trimming: another modest proposal

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
24 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Release note trimming: another modest proposal

Tom Lane-2
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.

Thoughts?

                        regards, tom lane

Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Dean Rasheed-3
On 5 August 2018 at 23:57, Tom Lane <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Jonathan S. Katz-3
In reply to this post by Tom Lane-2

On Aug 5, 2018, at 6:57 PM, Tom Lane <[hidden email]> 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? 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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Tom Lane-2
"Jonathan S. Katz" <[hidden email]> writes:
>> On Aug 5, 2018, at 6:57 PM, Tom Lane <[hidden email]> 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.

(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

Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Jonathan S. Katz-3

> On Aug 6, 2018, at 11:09 AM, Tom Lane <[hidden email]> wrote:
>
> "Jonathan S. Katz" <[hidden email]> writes:
>>> On Aug 5, 2018, at 6:57 PM, Tom Lane <[hidden email]> 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

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Tom Lane-2
"Jonathan S. Katz" <[hidden email]> 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"
it might be worth doing.

                        regards, tom lane

Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Alvaro Herrera-9
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"
> 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

Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Jonathan S. Katz-3
In reply to this post by Tom Lane-2

> On Aug 6, 2018, at 11:47 AM, Tom Lane <[hidden email]> wrote:
>
> "Jonathan S. Katz" <[hidden email]> 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"
> 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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Tom Lane-2
"Jonathan S. Katz" <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Jonathan S. Katz-3

> On Aug 6, 2018, at 12:55 PM, Tom Lane <[hidden email]> wrote:
>
> "Jonathan S. Katz" <[hidden email]> 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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Jonathan S. Katz-3

On Aug 6, 2018, at 1:22 PM, Jonathan S. Katz <[hidden email]> 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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Jonathan S. Katz-3

On Aug 6, 2018, at 2:05 PM, Jonathan S. Katz <[hidden email]> wrote:


On Aug 6, 2018, at 1:22 PM, Jonathan S. Katz <[hidden email]> 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




signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Tom Lane-2
"Jonathan S. Katz" <[hidden email]> writes:

> On Aug 6, 2018, at 2:05 PM, Jonathan S. Katz <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Tom Lane-2
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

Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Jonathan S. Katz-3

> On Aug 6, 2018, at 3:27 PM, Tom Lane <[hidden email]> 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

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Tom Lane-2
"Jonathan S. Katz" <[hidden email]> writes:
>> On Aug 6, 2018, at 3:27 PM, Tom Lane <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Jonathan S. Katz-3

> On Aug 6, 2018, at 3:37 PM, Tom Lane <[hidden email]> wrote:
>
> "Jonathan S. Katz" <[hidden email]> writes:
>>> On Aug 6, 2018, at 3:27 PM, Tom Lane <[hidden email]> 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


release-notes.patch (8K) Download Attachment
signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Michael Paquier-2
In reply to this post by Dean Rasheed-3
On Mon, Aug 06, 2018 at 08:14:23AM +0100, Dean Rasheed wrote:
> On 5 August 2018 at 23:57, Tom Lane <[hidden email]> 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

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Chris Travers-5
In reply to this post by Tom Lane-2


On Mon, Aug 6, 2018, 05:57 Tom Lane <[hidden email]> 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.

Thoughts?

                        regards, tom lane

Reply | Threaded
Open this post in threaded view
|

Re: Release note trimming: another modest proposal

Bruce Momjian
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  <[hidden email]>        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 +

12
Previous Thread Next Thread