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