Bug#1016832: release-notes: Chapter 4 Upgrading commands are spread out over 20 pages

[Daniel Lewart]

Package: release-notes
Severity: wishlist

Debian Documention Team,

Chapter 4. "Upgrades from Debian 10 (buster)" has commands spread out
over 20 pages. I think many (most?) admins would enjoy a quick checklist
or summary.

How about a section like the one below at the end of the Chapter?

Thank you!
Daniel Lewart
Urbana, Illinois
---
Basic System Quick Upgrade

For a basic system:
* Latest stable point release
* Debian packages only
* No APT pinning
* Sufficient disk space (1 GB free for /var)
the following upgrade procedures should work.

Edit /etc/apt/sources.list:
deb http://deb.debian.org/debian &releasename; main [contrib] [non-free]
deb http://security.debian.org &releasename;-security main [contrib] [non-free]
deb http://deb.debian.org/debian &releasename;-updates main [contrib] [non-free]

# apt update
# apt autoclean
# apt upgrade --without-new-pkgs 2>&1 | tee &releasename;1.log
# apt full-upgrade 2>&1 | tee &releasename;2.log
# apt autopurge
# reboot

Review and clean up:
# find /etc -name '*.dpkg-*' -o -name '*.ucf-*' -o -name '*.merge-error'

###

[RL]

Post by Daniel Lewart
Package: release-notes
Severity: wishlist
Debian Documention Team,

just a user here, but since no-one replied i thought id give my view

Post by Daniel Lewart
Chapter 4. "Upgrades from Debian 10 (buster)" has commands spread out
over 20 pages. I think many (most?) admins would enjoy a quick checklist
or summary.

I think you are onto something, but i think that a checklist might not
be the way to go (reasons below).

I do think the structure of release-notes could be clearer about which
things are 'generic good practice' and which are release-specific.


The first category of generic good practice includes things like running
script(1) and informing users of downtime: people that have done
upgrades several times can skip these, but it's not always obvious
which these are, or where the division lies - i'd suggest putting these
into one chapter for example. The second set are the things that
everyone wants to read - changes to security section, whether the kernel
needs to be upgraded first etc. (Perhaps there is a third set about new
packages)

But I'd suggest against a checklist for a couple of reasons

* Encourages duplication. All the content will need to be written twice
how do you decide what, if anything, to leave out of the checklist. And
if the two say slightly different things then how will a user know which
is correct?

* Cant be automatic - eg your example "edit sources.list"

* Discourages understanding - same example, if the checklist doesnt
explain that there was a change here then some people will probably
miss it and will request more text in the checklist.