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

Bug#991627: installation-guide: expand firmware-related documentation

Source: installation-guide
Severity: important
X-Debbugs-Cc: debian-release@lists.debian.org, isenkram@packages.debian.org

[ RT and isenkram maintainers in the loop for information ]


This bug report is about the first part of the proposal outlined in this
other bug report:

which is trying to be a bit more helpful regarding firmware problems.

Looking at the amd64 documentation, there are several places where
firmware is mentioned:
 - 2.1.5, which basically points at 2.2.
   → https://www.debian.org/releases/bullseye/amd64/ch02s01#gfx
 - 2.2, which pretends graphics cards should work at least minimally
   (which tends not to be true), and which also points at 6.4.
   → https://www.debian.org/releases/bullseye/amd64/ch02s02 
 - 6.4, which documents a number of things.
   → https://www.debian.org/releases/bullseye/amd64/ch06s04

At first glance, I'm proposing:
 - not to change 2.1.5;
 - to amend 2.2, mentioning graphics cards might be problematic, and
   mentioning nomodeset as a possible workaround (plus another pointer
   at 6.4 right after that);
   → https://salsa.debian.org/installer-team/installation-guide/-/commit/09375ab4dfd366560d86bda554cd8d89c8920294
 - to extend 6.4, mentioning nomodeset again (for people who haven't
   seen 2.2 first), as well as an automated way to detect and install
   missing firmware.
   → https://salsa.debian.org/installer-team/installation-guide/-/commit/ed2ec80f30e4a024ed5d061e03251af5f7a28e00

For now, both commits are in a pu/firmware-v0 branch in the installation
guide repository.

I'm not very used to best practices when it comes to end-user doc in
general and to the installation-guide package in general, so I'd be
happy for other to build on those suggested changes, and amend/reword as

Some remarks:
 - There's a copy-paste for the “nomodeset” option, which I suppose
   could be avoided with some include logic. This might avoid duplicate
   works on the l10n front (which might be important due to the next
 - This is a *possible* workaround, as I have not been able to test it
   (I couldn't reproduce the black screen issue with test hardware). I
   plan to have some kind of survey organized to see if people affected
   by this issue can confirm.
 - 6.4.1 points at `unofficial/non-free/firmware/` which have been made
   to work out of the box (as much as possible) as detailed in #989863,
   but “the archive (tar or zip) on a separate support” use case wasn't
   tackled yet (in particular detecting graphics firmware might be
   required, even if the installer didn't spot that on its own due to
   using generic drivers). I don't think it makes sense to document that
   separately, as we might improve this in a point release, and the
   “nomodeset workaround” + “isenkram procedure” combination should be
   enough to fix things up from the installed system.
 - I documented in a note what happens with that “isenkram procedure”
   since mentioning non-free seemed to be the bare minimum. We might
   skip mentioning contrib though (see earlier note in 6.4.2; the logic
   is exactly the same though — same code!).
 - Documenting what isenkram-autoinstall-firmware does means we should
   check what happens for each major release, to keep up with the
   current implementation. Doing that once every two years doesn't seem
   unreasonable though.

Cyril Brulebois (kibi@debian.org)            <https://debamax.com/>
D-I release manager989863 -- Release team member -- Freelance Consultant

Reply to: