Re: releasenotes
On 12 October 2010 08:42, Justin B Rye <jbr@edlug.org.uk> wrote:
> How about this approach: after a release, every single paragraph
> gets tagged as "stale" (maybe giving it a strikethrough). This
> should apply at least in chapters like whats-new.dbk and issues.dbk;
> chapters like about.dbk and moreinfo.dbk are more resilient, but I'd
> still say tag the lot.
This is easy to do, but has to be done manually currently. We have the
'fixme' tag in the source although that does no (afaik) change the
formatting in any way it's apparent, it simply hides the text when
building the document.
> Release Notes for Debian GNU/Linux (Squeeze)
> --------------------------------------------
> Is this title still appropriate, now that Debian is more than a
> Linux distro?
I'm not sure about this, Squeeze will still be Debian GNU/Linux as the
kFreeBSD arches are a "technology preview" not a full release, nor
officially suppoted. In any case, we might want to find a replacement
for the &debian; entity maybe 'Debian Operating System'?
>
> CHAPTER 1 (about.dbk)
> ---------------------
> This part is largely impervious to obsolescence, though it does
> have a line tagged "TODO".
There is no TODO now.
> CHAPTER 2 (whats-new.dbk)
> -------------------------
> The tables of supported architectures and package version numbers
> may be automatically updatable, but the rest is stale. Even the
> stuff about proposed-updates seems to be on the brink.
Unfortunately, these are not updated automatically but, rather,
manually. The last line on 'proposed-updates' might be removed. Maybe
the proposed updates section could be moved to the Appendix, however,
within the 'Upgrading your lenny system' section.
Unfortunately, Debian developers have not contributed significantly to
http://wiki.debian.org/NewInSqueeze which means that we have to dig
out the information now from different sources (NEWS.Debian files in
packages, mailing lists info, planet.debian.org, you name it...)
> CHAPTER 3 (installing.dbk)
> --------------------------
> The "What's new in the installation system?" section is entirely
> stale. Loading firmware during installation and so on are all now
> *old* features. The entry on "new languages" can be edited into
> something accurate, and the compatibility warning for automated
> installs probably still holds true, but all the rest needs to be
> ripped out and replaced with information about, for instance, the
> new X-based graphical installer.
Yes, we need help from the d-i team to review this and provide
information on what has changed here for squeeze. Maybe
http://wiki.debian.org/DebianInstaller/SqueezeGoals could be used as a
basis here (since http://wiki.debian.org/NewInSqueeze does not
describe anything)
> CHAPTER 4 (upgrading.dbk)
> -------------------------
> Much of this is still basically true, it just needs the cobwebs
> wiped off - references to Linux 2.6.18 and backports.org, the stale
> package list in the "minimal system upgrade" section, and so on.
> There are even signs of parts having already been updated for
> Squeeze.
We certainly need to review the update procedure. In lenny we asked
users to do first a minimal upgrade, then upgrade the kernel and then
a full upgrade (sections 4.5.5 to 4.5.7). Sections 4.6 and 4.7 have to
be reviewed as they might not apply anymore or the recommended process
might change.
The only way to do this is by doing some test upgrades with different
(initial) setups.
> CHAPTER 5 (issues.dbk)
> ----------------------
> This begins with a TODO tag that claims it needs to be fixed for
> Lenny, so it's no surprise to find that it's full of stale items.
> Apart from the recurrent item on udev and the new item about
> linux-base, everything else needs to be ripped out.
Yes, all these could probably be ripped out. We might not now what to
put in there until we do upgrade tests and fully review the upgrade
reports to see if there are common issues that need to be documented.
> CHAPTER 6 (moreinfo.dbk)
> ------------------------
> A hardy perennial.
It could, however, be improved with new resources. Forums.debian.net
and ask.debian.net come to mind. Additionally we might want to
reference other bug reporting tools besides reportbug.
> APPENDICES
> ----------
> A) another perennial, though it seems to use the wrong relative
> release names.
This is because the release names where hardcoded here (instead of
using XML entities). Will fix.
> C) needs to go.
True, will remove in the next round.
> So what do we replace it with? Well, it's not much, but here are
> some of the rough notes I've accumulated over the past year or so in
> my "squeezewatch" file:
(..)
Thanks for all this, but maybe this information should be best placed
in the NewinSqueeze wiki file. Could you please include them there and
expand the information a little bit? That would be very much
appreciated.
We should also ask Debian developers (through d-d-a?) to document the
most relevant changes there to so that the Release Notes editors have
something to start with coming (hopefully) from authoritative sources
(besides the NEWS files and the bug reports to the RN themselves, that
is).
Regards
Jaer
Reply to: