[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: releasenotes

Simon Paillard wrote:
> Justin B Rye wrote:
>> People are talking about the Squeeze release notes being nearly
>> ready for a call for translations.
> Then these people were certainly drunk or worse :-)

Last week's Release Team meeting minutes:
# The release notes for Squeeze are progressing well and a call for
# translations will be made soon.

>> I hope they are remembering that before the call for translations
>> there needs to be a quick debian-l10n-english proofreading
>> run-through, and before *that* we need to come up with some factually
>> accurate content.
> An option to avoid last minute full proofreading/translation, as we
> experienced by the past for Lenny, might be to proofreading patches
> posted against release-notes.

True; I'm hoping to have some spare time for this sort of thing in
the coming week or so.
>> When I look at the version on display at
>> http://www.debian.org/releases/squeeze/i386/release-notes/ I see
>> something so jam-packed with stale material that I wouldn't know
>> where to start reporting bugs, other than perhaps to recommend
>> throwing out chapter 2, chapter 3, much of chapter 4, chapter 5, and
>> of course appendix C.
> Julien Cristau from the release team is spotting issues and proposing updates.
> If you notice other issues, please don't hesitate to outline them.

More details below in case I don't get round to proper bugreports.
>> It has always seemed to me that using a summary of the notable
>> differences between Release-A and Release-B as the basis for our
>> summary of the notable differences between Release-B and Release-C
>> is a rather effective labour-wasting strategy.
> Could you expand your idea ? You consider it would be easier to start
> from scratch ?

That's how I would normally expect to proceed when I'm writing, say,
a letter to my mother telling her what I've been up to lately.  I
might copy/paste a few phrases over from the previous such text (or,
equally likely, the one before last), but since every word of it
needs to be checked for appropriateness I mostly just... write it.
Is that something that strikes developers as strange?

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.

When people are preparing the next release there's no reason they
shouldn't pick out a bit that's still true (or true again, thankyou
udev) and use it as the basis for a new section - or even just rip
off the tag and resurrect it.  But that should only happen when
somebody has actively thought about whether it belongs in the new
version - it shouldn't get back in merely because nobody who noticed
the problem remembered to submit a bugreport.

Here's a quick summary of the current state of the Release Notes:

 Release Notes for Debian GNU/Linux (Squeeze)
 Is this title still appropriate, now that Debian is more than a
 Linux distro?

 CHAPTER 1 (about.dbk)
 This part is largely impervious to obsolescence, though it does
 have a line tagged "TODO".

 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.

 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.

 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

 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.

 CHAPTER 6 (moreinfo.dbk)
 A hardy perennial.

 A) another perennial, though it seems to use the wrong relative
	release	names.
 B) the only part of this document that shows any sign of trying to
	implement a sensible best-before-date system.  Of course, it
	still needs to be updated.
 C) needs to go.

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:

 current status of backports, volatile...
 release arch changes (arm*, kfreebsd-*)
 section changes (e.g. kernel, video)
 LINUX 2.6.3x
 defaults for ext3 changing to data=writeback, relatime
 even IDE (PATA) drives now register as /dev/sdX (use labels!)
 ipv6: current status?
 KernelModeSetting support (dependent on hardware)
 pre-upgrade to a bpo kernel to appease udev

 console-setup reorganised (also used by X)
 dash is now default and Essential
 grub2 now = grub (and grub-pc), old grub = grub-legacy
 insserv defaulting to CONCURRENCY=makefile
 libpam-* debconf automation
 kernel-package getting more marginal
 new infrastructure: udisks, policykit-1, and consolekit
 xorg autoconfiguration (for most hardware)

JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package

Reply to: