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

Re: releasenotes

On Tue, Feb 01, 2011 at 01:36:54PM +0000, Justin B Rye wrote:
>  * 2.1.2 "Package management"
>    This bit's badly messed up:

>      The preferred program for interactive package management from a
>      terminal is aptitude. For a non-interactive command line interface
>      for package management, it is recommended to use apt-get. apt-get
>      is also the preferred tool for upgrades between major releases.

>    "Interactive" is a genuinely confusing misnomer; it turns out that
>    it means "full-screen Text User Interface" versus "Command Line
>    Interface", but what can it mean to recommend the *only* program
>    with such a TUI as the *preferred* one?

I'm not sure what you find confusing about this.  The aptitude TUI allows
you to interactively edit the upgrade solution.  The apt-get command does
not, it only presents the user with the option to confirm or reject the
proposed solution.  Referring to one as interactive and the other as
non-interactive may be imprecise, but I don't think it's really confusing.

And aptitude is certainly not the only TUI available.  dselect is still
provided.  There are even some who prefer it over aptitude.

>    Besides, on what grounds are the release notes telling me not to
>    use aptitude's CLI for routine package management on Squeeze?

On the grounds that aptitude's CLI is known to present pathological
solutions to straightforward requests.

>  How else am I going to perform an "aptitude purge ~c"?

 dpkg -l | awk '/^rc/ { print $2 }' | xargs dpkg --purge

But that's entirely beside the point.  We don't recommend apt-get over
aptitude because we like complicated shell pipelines.  We recommend apt-get
over aptitude because *aptitude is worse at the kind of basic upgrade
operations that the release notes are the documentation for*.  If you want
to use aptitude instead of apt-get for your own personal use, that's your
business - it has nothing to do with the release notes.

>    Also, "between major releases" is overstated: it wasn't true for
>    Etch-to-Lenny and may or may not be true for Squeeze-to-Wheezy.

It bloody well was for etch to lenny, we only failed to correct this in the
release notes because we ran out of time to run another round of upgrade
testing after making such a change.  It will be again for squeeze to wheezy.
The *only* advantages of aptitude over apt-get *as a non-interactive
upgrader* are all historical now that apt-get supports both
recommends-by-default and tracking of auto-installed packages.  Other than
that, the only things aptitude brings us as an upgrader are more complicated
library dependencies and a touchier solver.

>    I'm hoping this text can be rephrased as follows:

>      For users familiar with aptitude's full-screen mode, this is
>      the preferred interface for normal package management. However,
>      the recommended command line tool for the Lenny to Squeeze
>      upgrade is apt-get.

I don't believe this substantially improves the document, but it does
regress the translations that are already in progress.  I'm -1 on this
rewrite at this point.

>  * In the same section:
>    The paragraph about Recommends being installed by default (and the
>    footnote claiming that this is a change that increases diskspace
>    requirements) is a leftover New-In-Lennyism, and should go.

It is not leftover, this is new information that was not included in the
lenny release notes at time of release.  It's documented here so that people
will see it - adding it now to the lenny release notes isn't going to reach
the target audience.

The text should perhaps be tweaked to clarify that this was already true in

> upgrading.dbk:
>  * 4.2.1 "Review actions pending in package manager"
>    This uses a *different* unintelligible name for aptitude's TUI:

>      To perform this review, launch aptitude in "visual mode" and
>      press g ("Go").

>    That's visual as opposed to reading the screen via sonar, right?
>    We should standardise on a single comprehensible name for this:

>      To perform this review, launch aptitude in full-screen mode and
>      press g ("Go").

"visual mode" is the definitive name for this mode as used in the aptitude
manpage.  The release notes are not the place to be coining new terms for
things.  Please take the naming up with the aptitude maintainer.

>  * 4.4.5. "Upgrading the kernel and udev"
>    Should this crossreference to Xen?  As mentioned on d-l-e:
>    http://lists.debian.org/debian-l10n-english/2011/01/msg00106.html

Yes, I think that would be a good idea.  Can you follow up to the bug report
and mention that, perhaps proposing text?  (There's still no Xen text in the
release notes to cross-reference, so this is the best place to keep that
request to avoid losing track of it.)

>  * 4.6.1. "Installing the kernel metapackage"
>    The material about kernel-package versus "make deb-pkg" needs to be
>    rephrased slightly, but I'm not sure what it's safe to say.

>      There are some differences in these two approaches, please
>      consult the respective package's documentation.

>    This is an example of my rule of thumb that any sentence with
>    "respective" in it needs reworking.  But as far as I can see there
>    *is* no packaged documentation for the "make deb-pkg" approach, so
>    we either need to find a URL or throw this line out.

I agree.  In general I'm unhappy with the changes to the documentation of
kernel-package for squeeze; we don't want to recommend users build their own
kernel for no reason, but I also don't think we should associate this with
"adventure".  I would favor a rewrite of this paragraph.

>  * 4.4.3. "Make sure you have sufficient space for the upgrade"
>    The tip to use deborphan is a leftover from Etch, and looking more
>    and more stale now that even apt itself provides better ways of
>    spotting obsolete libraries.  Can we get rid of it?

For long-lived systems, deborphan still tells me about packages that were
auto-installed before apt knew to track them and are now obsolete.  I think
we should keep this here for one more release cycle.

>  * 4.10. "Obsolete packages"
>    The item on replacements for apt-proxy is a bit long-winded.  Just
>    say "apt-proxy is no longer provided; although no automatic upgrade
>    path exists, users can switch to alternatives such as..."


> issues.dbk:

>  * 5.1.2. "mdadm metadata format change requires recent Grub"

>     To ensure a bootable system, please make sure to use grub-pc
>     1.98+20100720-1 or later, which is provided by Debian squeeze

>    How is this an upgrade issue if Squeeze's version *fixes* it?
>    Does it mean "please make sure the new version in Squeeze has
>    installed its GRUB bootloader code to the MBR"?

Yes, this is about making sure that the correct version of grub is being
used for booting, which is not ensured by installing / upgrading the grub-pc

>  * 5.1.3. "pam_userdb.so breakage with newer libdb"
>    This needs some hint at who'd be affected (i.e. users of exotic
>    login setups?)

The users affected by it are those who use pam_userdb.  Does that really
need to be spelled out?

>  * 5.3. "sieve service moving to its IANA-allocated port"
>    When it says:
>     Starting with the version 4.38 of the Debian netbase package, the
>     sieve service will be moved from port 2000 [...]
>    What it should say is:
>     In the version of netbase in Squeeze, the sieve service has been
>     moved from port 2000 [...]


>  * 5.5.2. "Device and other administrative permissions"
>    "See the consolekit documentation for more information" is cruel -
>    it doesn't even provide manpages.  Perhaps a link to
>    http://www.freedesktop.org/wiki/Software/ConsoleKit ?

Seems reasonable to me.

>  * 5.6.2. "Kernel mode setting"
>    Add some extra clues (a single hyphen would go a long way) that
>    this is kernelspace video mode-setting, not kernel-mode setting.
>    Obvious if you know; alarming bafflegab if you don't.

Ack to a hyphen.

Steve Langasek                   Give me a lever long enough and a Free OS
Debian Developer                   to set it on, and I can move the world.
Ubuntu Developer                                    http://www.debian.org/
slangasek@ubuntu.com                                     vorlon@debian.org

Reply to: