MIME-Version: 1.0
References: <19252.1533509841@sss.pgh.pa.us>
In-Reply-To: <19252.1533509841@sss.pgh.pa.us>
From: Chris Travers <chris.travers@gmail.com>
Date: Wed, 8 Aug 2018 21:53:42 +0700
Message-ID: 
 <CAKt_ZfsDqo-yjYZbGFvuCfm7DPeqCyDFP5vvam125PzpzVr6yw@mail.gmail.com>
Subject: Re: Release note trimming: another modest proposal
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: pgsql-docs@lists.postgresql.org
Content-Type: multipart/alternative; boundary="000000000000fc7a440572edcf41"
Precedence: bulk

--000000000000fc7a440572edcf41
Content-Type: text/plain; charset="UTF-8"

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.

>
> Thoughts?
>
>                         regards, tom lane
>
>

--000000000000fc7a440572edcf41
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"auto"><div><br><br><div class=3D"gmail_quote"><div dir=3D"ltr">=
On Mon, Aug 6, 2018, 05:57 Tom Lane &lt;<a href=3D"mailto:tgl@sss.pgh.pa.us=
">tgl@sss.pgh.pa.us</a>&gt; wrote:<br></div><blockquote class=3D"gmail_quot=
e" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">=
We&#39;ve been around on this before, I know, but I got annoyed about it<br=
>
again while waiting around for test builds of the back-branch<br>
documentation.=C2=A0 I think that we need some policy about maintaining<br>
back-branch release notes that&#39;s not &quot;keep everything, forever&quo=
t;.<br>
The release notes are becoming an ever-larger fraction of the docs,<br>
and that&#39;s not good for documentation maintenance or for download<br>
bandwidth.=C2=A0 As an example, looking at the US-letter PDF version of<br>
the v10 docs, as things stand today:<br>
<br>
Total page count: 3550<br>
Pages in release notes for 10.x: 41 (1%)<br>
Pages in release notes for older branches: 898 (25%)<br>
Pages in release notes for pre-9.2 branches: 546 (15%)<br>
<br>
I&#39;ve not measured directly, but it&#39;s a reasonable assumption that i=
f<br>
we dropped all the back-branch release notes the documentation build<br>
time would drop about 25%, whichever format you were building.<br>
<br>
I also live in fear of overrunning TeX&#39;s hard-wired limits, in the<br>
back branches that depend on a TeX-based PDF toolchain.=C2=A0 We&#39;ve hit=
<br>
those before and been able to work around them, but I wouldn&#39;t count<br=
>
on doing so again, and I sure don&#39;t want to discover that we have a<br>
problem of that sort the day before a release deadline.=C2=A0 Trimming the<=
br>
release notes would definitely give us enough slack to not worry<br>
about that before all those branches are EOL.<br>
<br>
We&#39;ve discussed trimming the release notes before, and people have<br>
objected on the grounds that they like being able to access ancient<br>
notes from time to time.=C2=A0 I&#39;m not unsympathetic to that issue, but=
<br>
does that access point need to be our daily working documentation?<br>
<br>
Anyway, I&#39;d like to propose a compromise position that I don&#39;t thin=
k<br>
has been discussed before: let&#39;s drop release notes for branches<br>
that were already EOL when a given branch was released.=C2=A0 So for<br>
example, 9.3 and before would go away from v12, due out next year.<br>
Working backwards, we&#39;d drop 9.1 and before from v10, giving the 15%<br=
>
savings in page count that I showed above.=C2=A0 A quick measurement says<b=
r>
that would also trim the size of the v10 tarball by about 4%, which<br>
is not a lot maybe but it&#39;s noticeable across a lot of downloads.<br>
<br>
It seems to me that this would still provide enough historical<br>
info for just about any ordinary interest.=C2=A0 We could discuss ways<br>
of making a complete release-note archive available somewhere,<br>
if &quot;go dig in the git repo&quot; doesn&#39;t seem like an adequate ans=
wer<br>
for that.<br></blockquote></div></div><div dir=3D"auto"><br></div><div dir=
=3D"auto">Works for me.=C2=A0 Especially with a release note archive availa=
ble somewhere.</div><div dir=3D"auto"><div class=3D"gmail_quote"><blockquot=
e class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc sol=
id;padding-left:1ex">
<br>
Thoughts?<br>
<br>
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=
=A0 =C2=A0 regards, tom lane<br>
<br>
</blockquote></div></div></div>

--000000000000fc7a440572edcf41--