[Lvfs-announce] Putting warnings into the update description

Richard Hughes <[email protected]> Tue, 4 Oct 2022 13:52:46 +0100
Newsgroups dev.linux.lists.lvfs-announce
Message-ID <CAD2FfiGoHJkDYCp6U2iY7CsL7SH0RuPvmDA791ebq_PUve6zDQ@mail.gmail.com>
Hi all,

I've just deployed a new LVFS version that enforces something that has
been inferred for some time. You now cannot put text like:

* Do NOT turn off your computer or remove the AC adapter while update
is in progress
* Do not turn off your computer or remove the power adaptor while the
update is in progress
* Do not restart your computer while the update is in progress.

..into the update description OR the post-install update dialog. This
warning is now added automatically and specified per-protocol, which
allows us to:

 * Fix the 17 (!) different versions of this string in the 678 update
descriptions that use a variant of it
 * Move the release-notes warning text to a post-update pre-reboot
warning *modal dialog* for firmware that depends on a new enough fwupd
version
 * Append a standardized and reviewed string to the release notes for
firmware that does not depend on a fwupd version >= 1.4.5
 * Translate the warning text automatically in the front-end for
future fwupdmgr and gnome-software/gnome-firmware versions -- which
means that users who don't speak English are provided the warning in a
language that they understand.

I've also added a fsck action which is running now which removes all
17 variants of the existing message strings from all firmware as we're
going to use the per-protocol standardized one in all cases.

No action is required; everything should continue to work as before,
but I figured I should let everyone know. As a reminder other strings
which are not appropriate for the update release details are:

* Telling the user scary things that are not quite true: e.g. "Your
computer may not properly function until you shut down or reboot PC."
* Including what other products also contain this hardware e.g.
"Supported Product Scope : Foo, Bar, Baz"
* Including sections, with no content, e.g. "This update fixes the
following important problems: Nothing"
* Including confusing information that isn't needed before the update
is deployed, e.g. "The computer shall be restarted after updating
firmware completely."

We're now distributing more than 5 MILLION UPDATES A MONTH on the
LVFS, and the #1 feedback from end users is that the update
descriptions are either incomplete, difficult to understand or just
completely missing. If we're showing text to millions of users then we
HAVE to work harder on the information we're providing them. I don't
think it's appropriate to name and shame vendors that use update
descriptions like "Addresses Misc Issues" but users really are
noticing which vendors care and which don't. I'm happy to keep working
on abstracting out functionality like client-side translated warnings,
but I do need some help from the OEMs/ODMs and IBVs to provide high
quality release notes.

If anyone has any questions or concerns please let me know.

Richard.