public inbox for [email protected]  

help / color / mirror / Atom feed

From: Jonathan S. Katz <[email protected]>
To: Tom Lane <[email protected]>
Cc: [email protected]
Subject: Re: Release note trimming: another modest proposal
Date: Mon, 6 Aug 2018 10:41:28 -0400
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>


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



Attachments:

  [application/pgp-signature] signature.asc (833B, 3-signature.asc)
  download

view thread (58+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: Release note trimming: another modest proposal
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox