Re: Please proof-read Debian 5.0 ("lenny") release notes
Some more notes on the web version of:
> Release Notes for Debian GNU/Linux 5.0 (lenny), Intel x86
[...]
> Adam Di Carlo
>
> prior release
"Prior" is an odd word choice here; I'd advise s/prior/previous/g
[...]
>
> Jens Seidel
>
> German translation, innumerous contributions<jensseidel@users.sf.net>
And the word "innumerous" is even odder, if it exists at all. Should
be either numerous or innumerable, each time.
[...]
> Chapter 1. Introduction
[...]
> This document informs users of the Debian GNU/Linux distribution
> about major changes in version 5.0 (codenamed "lenny").
Stylistic tweak:
This document is designed to inform users of the Debian GNU/Linux
distribution about the major changes in version 5.0 (codenamed
"lenny").
> The release notes provide information on how to upgrade safely from
> the release 4.0 (codenamed etch) to the current release and inform
^^^
Probably drop that "the".
> users of known potential issues they could encounter in that process.
>
> You can get the most recent version of this document from http://
> www.debian.org/releases/lenny/releasenotes. If in doubt, check the
> date of document at the first page and make sure you are reading a
^the on ?
> current version.
Rephrase slightly:
date on the first page to make sure you are reading a current version.
[...]
> 1.1. Reporting bugs on this document
You report bugs "on" packages, but for a document "in" sounds more
natural.
> We have attempted to test all the different upgrade steps described
> in this document and we have also tried to anticipate all the
^^^^^^^^^^^^^^^^^^
Pointless repetition; snip this phrase.
> possible issues our users might encounter.
>
> Nevertheless, if you think you have found any bug in this
> documentation (incorrect information or information that is missing),
Better ordered as "if you think you have found a bug (missing or
incorrect information) in this documentation".
[...]
> The status of your package database before and after the upgrade:
> dpkg's status database available at /var/lib/dpkg/status and
^, ^,
> aptitude's package state information, available at /var/lib/
> aptitude/pkgstates. You should have made a backup before the
> upgrade as described at Section 4.1.1, “Back up any data or
> configuration information”, but you can also find backups of this
> information in /var/backups.
>
> ● Session logs using script, as described in Section 4.5.1,
^created
> “Recording the session”.
>
> ● Your apt logs, available at /var/log/apt/term.log or your
^,
> aptitude logs, available at /var/log/aptitude.
[...]
> The source of this document is in DocBook XML format. The HTML
> version is generated using docbook-xsl and xsltproc. The PDF version
> is generated using dblatex or xmlroff. Sources for the Release Notes
> are available in the SVN repository of the Debian Documentation
> Project. You can use the web interface to access its files
> individually through the web and see their changes. For more
> information on how to access the SVN please consult the Debian
> Documentation Project SVN pages.
The SVN access HOWTO is accessible via SVN?! Cheers.
> Chapter 2. What's new in Debian GNU/Linux 5.0
[...]
> The official Debian GNU/Linux distribution now ships on 4 to 5 binary
> DVDs or 28 to 32 binary CDs (depending on the architecture) and 4
> source DVDs or 28 source CDs. Additionally, there is a multi-arch
> DVD, with a subset of the release for the amd64 and i386
> architectures, and the source code. For the first time, Debian GNU/
> Linux is also released as Blu-ray images, also for the amd64 and i386
> architectures, and the source code.
Too many "and"s; s/and the source code/along with the source code/g
> Debian now supports Linux Standards Base (LSB), version 3.2.
^
The comma implies that etch didn't support LSB (at all).
> 2.1.1. Package management
>
> aptitude is the preferred program for package management from
^the
> console. aptitude supports most command line operations of apt-get
> and has proven to be better at dependency resolution than apt-get. If
> you are still using dselect, you should switch to aptitude as the
> official frontend for package management.
front-end
Is this trying to say that it supports the same syntax or that it can
perform the same functions? If the latter, just what package
management operations might etch users of apt-get be used to that
they won't be able to perform via aptitude? I'd suggest:
The preferred program for package management from the command line
is aptitude, which can perform the same package management functions
as apt-get and has proven to be better at dependency resolution. If
you are still using dselect, you should switch to aptitude as the
official front-end for package management.
But then again see 4.5.4.
[...]
> 2.1.2. The proposed-updates section
>
> All changes to the released, stable (and oldstable) distribution go
Say:
All changes to the released stable distribution (and to oldstable) go
> through an extended testing period before they are accepted into the
> archives. Each such update of the stable (oldstable) release is
(or oldstable)
> called a point release. Preparation of point releases is done through
> the proposed-updates mechanism.
Shouldn't there be some mention here of the fact that some of them
may be rejected updates that it would be inadvisable to set up your
production-critical machines to install automatically? I mean, if
that wasn't true they'd just go into stable, wouldn't they?
> 2.2. System improvements
>
> New default inet superdaemon
>
> The default inet superdaemon for lenny is openbsd-inetd instead
> of netkit-inetd. It will not be started if no services are
In both etch and lenny, netkit-inetd is a virtual package provided
by inetutils-inetd and openbsd-inetd. Presumably if this is true it
should talk about "instead of inetutils-inetd"?
> configured, which is true by default. The new default daemon will
configured, as is the case by default.
> be installed automatically on upgrade.
>
> New default syslog daemon
>
> The default syslog daemon for lenny is rsyslog instead of
> sysklogd. rsyslog is quite compatible to stock sysklogd and can
> be used as a drop-in replacement. If you have custom logging
> rules, you should migrate them to the new configuration file /etc
> /rsyslog.conf.
Does "quite" there mean "moderately" or "entirely"?
Talking about the source package "sysklogd" instead of the actual
daemons (syslogd and klogd, in two separate packages) is unhelpful.
I'd rephrase it completely, if only to make this section less
repetitive:
The package rsyslog takes over as default system and kernel
logging daemon for lenny, replacing syslogd and klogd. With
stock logging rules, it can be used as a drop-in replacement;
if you have custom rules, you should migrate them to the new
configuration file, /etc/rsyslog.conf.
[...]
> 2.3. Debian Live
>
> With lenny Debian presents official Live systems for the amd64 and
> i386 architectures.
>
> A Debian Live system is a Debian system that can be booted directly
> from removable media (CD-ROMs, DVDs, USB keys) or from another
> computer over the network without the need of installation. The
for
> images were produced by a tool named live-helper, which allows to
are !!!!!!
> easily create own custom live images. More information about the
!!!
> Debian Live project can be found at http://
> debian-live.alioth.debian.org/.
Painfully non-native-speakerish abuse of "allows" and "own". Try
"which can easily be used to create custom live images".
> 2.4. Major kernel-related changes
>
> Debian GNU/Linux 5.0 ships with kernel version 2.6.26 for all
> architectures.
>
> There have been major changes both in the kernel itself and in the
> packaging of the kernel for Debian. Some of these changes complicate
> the upgrade procedure and can potentially result in problems while
> rebooting the system after the upgrade to lenny. This section gives
> an overview of the most important changes; potential issues and
> information on how to work around them is included in later chapters.
??
Is, singular? Rearrange:
an overview of the most important changes; information on how to
work around potential issues is included in later chapters.
> 2.4.1. Changes in kernel packaging
>
> New OpenVZ kernel flavor
>
> Along with Linux-VServer container solution introduced in etch
> Debian GNU/Linux now provides pre-built kernel images for OpenVZ,
> another container solution. OpenVZ offers some nice features over
> Linux-VServer (like live migration) at the expense of a slightly
> higher overhead.
I had to read this several times to understand it (what's a
"container solution"?); maybe:
The lenny release of Debian GNU/Linux provides pre-built kernel
images for OpenVZ, a second virtualization solution to go
alongside the Linux-VServer support included in etch.
Advantages of OpenVZ include support for live migration, at
the expense of a slightly higher overhead.
> Kernel x86 packages unified
>
> In previous releases there was special -k7 kernel flavour for
^a
> 32-bit AMD Athlon/Duron/Sempron processors. This flavour was
> dropped and was replaced by a single variant -686 which handles
> all AMD/Intel/VIA 686 class processors.
s/flavour/flavor/; also, this phrasing implies that -686 is new.
In previous releases there was a special -k7 kernel flavor for
32-bit AMD Athlon/Duron/Sempron processors. This variant has
been dropped; the single flavour -686 now handles all
AMD/Intel/VIA 686 class processors.
> Where possible, dummy transition packages that depend on the new
> packages have been provided for the dropped packages.
>
> 2.4.2. New utilities to generate initrds
>
> The Debian kernel image packages for Intel x86 require an initrd for
> booting the system. Because of changes in the kernel, the utility
> used to generate initrds in etch, initrd-tools is not included
^, is no longer included.
> anymore. Two new utilities have been developed that replace it:
> initramfs-tools and yaird. The concepts behind the new utilities are
> very different; an overview is available on the Debian Wiki. Both
> will generate an initrd using the initramfs file system, which is a
> compressed cpio archive. The default and recommended utility is
> initramfs-tools. yaird is not included in lenny.
So why mention it?
> Upgrading to a lenny kernel will cause initramfs-tools to be
> installed by default. If you are upgrading from a 2.4 kernel to a 2.6
> Debian kernel, you must use initramfs-tools.
Upgrading even to etch's 2.6.18 kernels will pull in initramfs-tools
(or, impossibly on lenny, yaird), so this paragraph at least is
surely stale.
> 2.5. Emdebian 1.0 (based on Debian GNU/Linux lenny 5.0)
>
> Lenny now contains the build tools for Emdebian which allow Debian
> source packages to be cross-built and shrunk to suit embedded ARM
> systems.
Is that a restrictive, defining "which" (those particular build
tools for Emdebian that have functionality X) or a nonrestrictive
(merely descriptive) "which" (build tools, which also by the way
have functionality X)? I'm guessing the latter, in which case
s/ which/, which/.
[...]
> Chapter 3. Installation System
[...]
> 3.1. What's new in the installation system?
>
> There has been a lot of development on the Debian Installer since its
> first official release with Debian GNU/Linux 3.1 (“sarge”) resulting
? ? ^,
> in both improved hardware support and some exciting new features.
Why is the codename in quotes this time?
[...]
> The installation media are now provided with an application that
> allows preparing the system to install Debian, from Microsoft
X
> Windows environments.
Better without the comma.
>
> SATA RAID support
Empty section?
> Early upgrade of packages with security fixes
>
> When used with a functional network access, the installer will
X
> upgrade all packages that were updated since the initial release
have been updated
> of lenny. This upgrade happens during the installation step,
> before the installed system is booted.
>
> As a consequence, the installed system is less likely to be
> vulnerable to security issues that were discovered and fixed
> between the release time of lenny and the installation time.
>
> Support for volatile
>
> The installer can now optionally setup the installed system to
set up
The separable verb is two words.
> use updated packages from volatile.debian.org. That archive hosts
> packages that provide data that needs to be regularly updated
> over time, such as timezones definitions, anti-virus signature
> files, etc.
Thatty. Say "This archive hosts packages providing data..."
[...]
> Support for relatime mount options
>
> The installer can now setup partitions with the relatime mount
set up
> option, allowing access time on files and directories to be
so that is
> updated only if the previous access time was earlier than the
> current modify or change time.
Just for once, the problem with "allows" here is semantic: access
times don't particularly appreciate being "allowed" to change in
fewer situations.
[...]
> New languages
>
> Thanks to the huge efforts of translators, Debian can now be
> installed in 63 languages (50 using the text-based installation
> user interface and 13 supported only with the graphical user
> interface). This is five languages more than in etch. Languages
> added in this release include Amharic, Marathi, Irish, Northern
> Sami, Serbian. Due to lack of translation updates, one language
^and
> has been dropped in this release: Estonian. Another language that
> was disabled in etch has been reactivated: Welsh.
>
> The languages that can only be selected using the graphical
> installer as their character sets cannot be presented in a
> non-graphical environment are: Amharic, Bengali, Dzongkha,
> Gujarati, Hindi, Georgian, Khmer, Malayalam, Marathi, Nepali,
> Punjabi, Tamil and Thai.
^,
(My standardisation on "Harvard comma" is just a stylistic nitpick.)
[...]
> 3.1.3. Install Debian GNU/Linux with a braille display
s/braille/Braille/g to mark Louis B's bicentenary.
[...]
> Chapter 4. Upgrades from previous releases
[...]
> Any package installation operation must be run with superuser
> privileges, so either login as root or use su or sudo to gain the
log in (like "back up", "set up" etc.)
> necessary access rights.
>
> The upgrade has a few preconditions; you should check them before
> actually executing the upgrade.
>
> 4.1.2. Inform users in advance
>
> It's wise to inform all users in advance of any upgrades you're
> planning, although users accessing your system via an ssh connection
> should notice little during the upgrade, and should be able to
> continue working.
>
> If you wish to take extra precautions, back up or unmount users'
> partitions (/home) before upgrading.
This implies there are users who (each) have partitions; just say
"back up or unmount the /home partition".
[...]
> Note, however, that doing this will cause initramfs-tools to install
> only those modules that are required for the particular hardware that
> it is run on, onto the initramfs; as such, if you want to generate a
> boot medium that will work on more hardware than just the one you're
> generating it on, you should leave the setting to
Various slightly grotty bits of wording.
Note, however, that doing this will cause initramfs-tools to install
onto the initramfs only those modules that are required for the
particular hardware that it is being run on. If you want to generate
boot media that will work on more hardware than just the machine
you're generating it on, you should leave the line as:
[...]
> Because of this you should review if there are any pending actions in
> the package manager aptitude. If a package is scheduled for removal
> or update in the package manager, it might negatively impact the
> upgrade procedure. Note that correcting this is only possible if your
> sources.list still points to etch; and not to stable or lenny; see
X
> Section A.2, “Checking your sources list”.
>
> To do this, you have to run aptitude in “visual mode” and press g
To perform this review, launch aptitude in “visual mode” and press g
(Why "visual", anyway? How do I access olfactory mode?)
[...]
> 4.2.5.1. Using backports.org packages
[...]
> The backports.org repository contains packages from “testing”, but
> with reduced version numbers, therefore the upgrade path from etch
> backports to lenny is saved. However, there are a few backports only
> which are made from unstable (security updates and the following
> exceptions: Firefox, kernel, OpenOffice.org, X.Org).
The backports.org repository mainly contains packages from “testing”,
with reduced version numbers so that the upgrade path from etch
backports to lenny still works. However, there are a few backports
which are made from unstable: security updates, plus the following
exceptions: Firefox, the Linux kernel, OpenOffice.org, and X.Org.
> 4.4. Preparing sources for APT
>
APT or apt? I'd say s/apt/APT/ (but not quite everywhere).
[...]
> apt will consider all packages that can be found via any “deb” line,
APT
> and install the package with the highest version number, giving
> priority to the first mentioned lines (that way, in case of multiple
the first line in the file (thus where you have multiple
> mirror locations, you'd typically first name a local harddisk, then
> CD-ROMs, and then HTTP/FTP mirrors).
[...]
> ● Remove old packages you no longer use. If you have
> popularity-contest installed, you can use popcon-largest-unused
> to list the packages you do not use in the system that occupy the
> most space. [...]
Simpler,
to list the packages you do not use that occupy the most space.
> [...] You can also use deborphan or debfoster to find
> obsolete packages (see Section 4.11, “Obsolete packages” ).
> Alternatively you can start aptitude in “visual mode” and find
> obsolete packages under “Obsolete and Locally Created Packages”.
None of this has anything to do with "old packages you no longer
use", so if you're going to keep this information you should change
the misleading first sentence to (say) "Remove forgotten packages".
> ● Remove packages taking up too much space, which are not currently
> needed (you can always reinstall them after the upgrade). You can
> list the packages that take up most of the disk space with dpigs
> (available in the debian-goodies package) or with wajig (running
> wajig size).
Slightly smoother as:
● Remove packages that take up too much space and are not currently
needed (you can always reinstall them after the upgrade). You can
list the packages that take up the most disk space with dpigs
(available in the debian-goodies package) or with wajig (running
wajig size).
[...]
> 4.5.4. Upgrade apt and/or aptitude first
(Here it's apt, the installed package, not APT, the overall system.)
> Several bug reports have shown that the versions of the aptitude and
> apt packages in etch are often unable to handle the upgrade to lenny.
> In lenny, apt better deals with complex chains of packages requiring
is better at dealing with
> immediate configuration and aptitude is smarter in searching
at? ^for
> solutions for satisfying the dependencies. As these two features are
to satisfy These
> heavily involved during the dist-upgrade to lenny, it is then
, so it is
> required to upgrade those two packages before upgrading anything
necessary to upgrade these
> else. For apt, run:
[...]
> 4.5.6. Minimal system upgrade
>
> Because of certain necessary package conflicts between etch and
> lenny, running aptitude dist-upgrade directly will often remove large
> numbers of packages that you will want to keep. We therefore
> recommend a two-part upgrade process, first a minimal upgrade to
:
> overcome these conflicts, then a full dist-upgrade.
[...]
> Some common packages that are expected to be removed include
> base-config, hotplug, xlibs, netkit-inetd, python2.3, xfree86-common,
> and xserver-common. For more information about packages obsoleted in
> lenny, see Section 4.11, “Obsolete packages”.
See previous review, "Obsolete sections".
> 4.5.6.1. Upgrading a desktop system
> 4.5.6.2. Upgrading a system with some X packages installed
> 4.5.6.3. Upgrading a system with no X support installed
> 4.5.7. Upgrading the kernel
> 4.5.9. Getting package signatures
Did you guys _really_ start the lenny release notes by cloning the
etch release notes? What were you thinking?
> 4.5.10. Possible issues during upgrade
>
> If an operation using aptitude, apt-get, or dpkg fails with the error
>
> E: Dynamic MMap ran out of room
>
> the default cache space is insufficient. You can solve this by either
^^^^^^^^^
> removing or commenting lines you don't need in /etc/apt/sources.list
> or by increasing the cache size. The cache size can be increased by
^^^^^
Drop the second "by".
> 4.6. Upgrading your kernel and related packages
[...]
> Note also that if udev is not installed on your system, it is still
> possible to use hotplug for hardware discovery.
Remove at least this paragraph. Hotplug isn't in lenny.
> 4.6.1. Installing the kernel metapackage
[...]
> If you are unsure about which package to select, run uname -r and
> look for a package with a similar name. For example, if you see
> '2.4.27-3-686', it is recommended that you install
> linux-image-2.6-686. (Note that the 386 flavor no longer exists; if
> you are currently using the 386 kernel flavor, you should install the
> 486 flavor instead.) You may also use apt-cache to see a long
> description of each package in order to help choose the best one
> available. For example:
The -386 comment is stale, and should presumably be replaced with
one about -k7.
> 4.8. System boot hangs on Waiting for root file system
>
> Procedure to recover from /dev/hda that became /dev/sda
>
> Some users have reported that an upgrade could cause the kernel not
> finding the system root partition after a system reboot.
to find
>
> In such case, the system boot will hang on the following message:
^a
> Waiting for root file system ...
>
> and after a few seconds a bare busybox prompt will show.
appear.
[...]
> 4.8.1. How to avoid the problem before upgrading
[...]
s/uuid/UUID/g and s/labelling/labeling/g. We might mention
"/sbin/blkid -L /dev/hda6", but then again that's not in etch.
[...]
> Boot from Debian GNU/Linux installation media (CD/DVD) and when
> prompted, type rescue to launch rescue mode. Select your language,
pick
It's on a menu now!
> location, keyboard mapping; then let it configure the network (no
^and
> matter whether it succeeds or not). After a while, you should be
> asked for selecting the partition you want to use as root file
to select
> system. The proposed choices will look something like:
[...]
> Now you should have shell access as user root on your root file
> system mounted on /target. You need access to the contents of /boot,
^the
> /sbin and /usr directories of your harddisc, which should now be
on your hard disk,
> available under /target/boot, /target/sbin and /target/usr. If these
> directories need to be mounted from other partitions, do so (see /etc
> /fstab if you have no idea of which partition to mount).
[...]
> ### END DEBIAN AUTOMAGIC KERNELS LIST
>
> and replace every hda, hdb, hdc, hdd respectively with sda, sdb,
> sdc, sdd. Don't modify the line similar to:
Broken "respectively". As usual, my advice is just never to use the
word at all:
and replace every hda, hdb, hdc, or hdd with sda, sdb, sdc, or
sdd, as appropriate. Don't modify the line similar to:
[...]
> 4.11. Obsolete packages
[...]
> Detecting which packages in an updated system are “obsolete” is easy
> since the package management front-ends will mark them as such. If
> you are using aptitude, you will see a listing of these packages in
> the “Obsolete and Locally Created Packages” entry. dselect provides a
> similar section but the listing it presents might differ. Also, if
^\n\n
You're doing it again. If you want to talk about packages that are
"obsolete" in the "apt-get autoremove" sense, do it in a separate
paragraph from the ones that are "obsolete" in the not-in-lenny sense.
Better yet, explicitly mention that this is a different sense of the
word "obsolete".
The final paragraph in this section (talking about reasons packages
get removed from Debian) belongs with the above, not with the middle
paragraphs.
[...]
> ━━━━━━━━━━━━━━
[...]
> ^[7] The rules there are automatically generated by the script /etc/
> udev/rules.d/75-persistent-net-generator.rules to have persistent
> names for network interfaces. Delete this symlink to disable
> persistent device naming for NICs by udev.
Should this also mention that this _isn't_ where you'll find it on
your unupgraded etch system? What happens if you delete it before
the switch?
[...]
> Chapter 5. Issues to be aware of for lenny
[...]
(Continuing to ignore stale-looking paragraphs.)
> 5.3. NFS mounts now handled by nfs-common
>
> Since util-linux 2.13 NFS mounts are no longer handled by util-linux
> itself, but by nfs-common. Since not all systems mount NFS shares and
> to avoid a standard portmapper installation util-linux only suggests
> nfs-common. If you need to mount NFS shares, make sure nfs-common is
> installed on your system. The preinstallation script of the mount
> package checks, whether NFS mounts exist and aborts if /usr/sbin/
X
Surplus comma (which misleadingly implies "whether or not").
> mount.nfs from nfs-common is not present or if nfs-common is
> out-of-date. Either upgrade nfs-common, or unmount any NFS mounts
X
> prior to upgrading mount.
> 5.6. NIS and Network Manager
>
> The version of ypbind included with nis for lenny contains support
> for Network Manager. This support causes ypbind to disable NIS client
> functionality when Network Manager reports that the computer is
> disconnected from the network. Since Network Manager will usually
> report that the computer is disconnected when it is not in use, NIS
?????????????????????
> users with NIS client systems should ensure that Network Manager
> support is disabled on those systems.
Does this mean "when dbus isn't running"?
[...]
> Chapter 6. More information on Debian GNU/Linux
[...]
> Appendix A. Managing your etch system
Look fine.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and oh, look, 02:00 again, time for bed.
Reply to: