Skip to content

Update the fwupd exception documentation to match the reality today #347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
superm1 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update the fwupd exception documentation to match the reality today #347

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 16 additions & 27 deletions docs/SRU/reference/exception-firmware-updates.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,14 @@
Firmware Updates
================

This document describes the policy for updating the fwupd, fwupdate,
fwupd-signed and fwupdate-signed packages to new upstream versions in a
stable, supported distro (including LTS releases).
This document describes the policy for updating the fwupd and fwupd-efi
packages to new upstream versions in a stable, supported distro
(including LTS releases). The policy applies to Ubuntu 20.04 and newer.

fwupd is the firmware updating daemon used for performing updates on a
variety of devices both in and out of OS. Updates outside of the OS are
performed using UEFI capsules. fwupd versions older than 1.1.x used
fwupdate package and its EFI binary for performing UEFI capsule updates.
fwupd versions 1.1.x and newer have subsumed fwupdate and now maintains
and fully manage the lifecycle of the EFI binary.

performed using UEFI capsules. The EFI binary used for performing UEFI
capsule updatees is distributed in the fwupd-efi package.
Signed versions of the EFI binaries are in the respsective \*-signed
packages.

Expand All @@ -23,9 +20,8 @@ Mario Limonciello.
Due to the nature of the coverage of various UEFI implementations across
OEMs it's often difficult or impossible to foreshadow the impacts of a
given fix on other OEMs implementations. OEMs that run into a problem on
a particular version of fwupd/fwupdate can place information into the
metadata to prevent updates from running on versions of fwupd/fwupdate
that have known bugs.
a particular version of fwupd can place information into the metadata to
prevent updates from running on versions of fwupd that have known bugs.

Upstream does maintain stable release branches for distros like Ubuntu
to pick up when applicable without going to the latest version of fwupd
Expand All @@ -34,9 +30,8 @@ but still adopting fixes.
Metadata
--------

Due to this, upstream highly recommends distros to not backport
Copy link
Collaborator

@basak basak Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NAK. Upstream recommendations do not form SRU policy, and in this case contradicts SRU policy. Please do not emphasize this more. If anything, this should be removed because it implies that minimal patches to fix specific bugs are to be discouraged, contrary to Ubuntu SRU policy.

Copy link
Author

@superm1 superm1 Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal patches to fix specific bugs are to be discouraged, contrary to Ubuntu SRU policy.

That's why this is an exception document. Upstream is not going to support Ubuntu if Ubuntu decides to go and patch things willy-nilly.

Copy link
Collaborator

@basak basak Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nobody said anything about patching things willy-nilly. Ubuntu SRU policy is supposed to ensure that cherry-picks are properly reviewed and QA'd.

Copy link
Author

@superm1 superm1 Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ubuntu SRU policy is supposed to ensure that cherry-picks are properly reviewed and QA'd.

This requires an in-depth understanding of the code and potential implications for a cherry pick with a non-obvious dependency.

Copy link
Collaborator

@basak basak Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This requires an in-depth understanding of the code and potential implications for a cherry pick with a non-obvious dependency.

Absolutely. This is my expectation for any cherry-pick being made by a distribution.

individual patches so that OEMs can control only running fwupd/fwupdate
updates on safe combinations.
Upstream highly recommends distros to not backport individual patches so
that OEMs can control only running fwupd updates on safe combinations.

OEMs can add the following to their metadata:

Expand All @@ -52,25 +47,19 @@ OEMs can add the following to their metadata:
What can be SRUed
-----------------

New versions of fwupd and fwupdate can both be SRU'ed into older
releases provided following process is followed: On an Ubuntu release
that uses both fwupdate and fwupd (such as bionic and earlier):

**fwupdate**: tarball releases only. No backported individual patches.
Copy link
Collaborator

@basak basak Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No backported individual patches.

That may be your preference, but it's not the position of the Ubuntu SRU team. Please remove this. I appreciate it was there before; I don't know how that slipped in.

Copy link
Author

@superm1 superm1 Dec 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's an incredibly slippery slope to have backported patches when you have OEMs that specify requirements in their metadata on specific versions that go to LVFS.

Let me give you a hypothetical.

  • There is plugin foo-bar for OEM Baz.
  • Baz is testing with fwupd 2.0.0 in Ubuntu.
  • They find a bug, and it's fatal. They work with upstream to fix the bug. Great.
  • Upstream issues a 2.0.1 release.
  • Ubuntu backports the patch that fixes fatal issue instead of updating to 2.0.1.

What does the OEM put in their metadata for requirements for the update? If they put 2.0.0 and someone is running the old version in Ubuntu (or 2.0.0 in say Fedora) they're going to cause the fatal problem. If they put 2.0.1 then it's safe everywhere but Ubuntu won't offer the update.

The only safe and scalable way is that they put 2.0.1, and that Ubuntu picks up 2.0.1. Anything else and there is risk to their users.

Copy link
Collaborator

@basak basak Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My view is that your hypothetical situation illustrates precisely how upstream's version-check based architecture is flawed. Distributions have cherry-picked fixes as they feel appropriate pretty much forever. Debian in particular is by design supposed to deviate from upstream's preferences when Debian's own preferences (eg. Debian Policy, but also in other areas not specifically in Policy, such as privacy leak/phone home implications) require it. Upstream's choice in locking update downloads in to specific microrelease versions therefore plays poorly with existing practice in our ecosystem.

The right way to do this is for the metadata to state that some specific feature or bugfix (eg. with a bug reference) is required for a given update to work. Then the metadata should not say ">= 2.0.1" but "baseline 2.0 features with bugfix 123 and bugfix 125" for example. Even this should be applied sparingly when it is specifically necessary to prevent the sort of fatal issue you describe.

If upstream doesn't wish to fix their architecture, then we can work around it in distro. For example, we could add a mapping in a cherry-pick from ">= 2.0.1" to "baseline 2.0 features with bugfix 123 and bugfix 125" and then apply that check instead.

There are other ways to do this, but the principle remains that every distribution is entitled to cherry-pick as required as it feels appropriate to meet the needs of its individual users.

Of course doing this properly can require more effort and more maintenance, so we might well choose to take an upstream microrelease instead. SRU policy specifically permits this when all changes meet our quality requirements.

Copy link
Author

@superm1 superm1 Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My view is that your hypothetical situation

It's been a while now - but we had this exact issue happen early on which is why this architecture was introduced and why the exception documentation was written this way.

Upstream's choice in locking update downloads in to specific microrelease versions therefore plays poorly with existing practice in our ecosystem.

It's actually an OEM's choice that mirrors their experience in failures from QA. An OEM won't introduce metadata to gate a version unless they've found a problem.

Of course doing this properly can require more effort and more maintenance, so we might well choose to take an upstream microrelease instead. SRU policy specifically permits this when all changes meet our quality requirements.

The only reason the microreleases exist is to support distros like Ubuntu which stay on older major releases.
If Ubuntu is going to stop taking microreleases it's a waste of effort upstream.

Copy link
Collaborator

@basak basak Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If Ubuntu is going to stop taking microreleases it's a waste of effort upstream.

I made no suggestion that Ubuntu should stop taking microreleases. In fact I specifically pointed out that our policy explicitly permits them (with conditions). I'm merely refusing to implement a ban on cherry-picking or a recommendation contrary to normal Ubuntu packaging practice. Microrelease updates are still welcome, probably preferable, and can follow the documentation (or its update) as normal.

If a tarball release isn't available, make upstream release one.

**fwupd**: fwupd releases in the 1.0.x series.

On an Ubuntu release that uses fwupd but not fwupdate:
New versions of fwupd and fwupd-efi can both be SRU'ed into older
releases provided following process is followed:

Stay with the same stable release branch that was launched with that
release. For example 1_1_X branch or 1_2_X branch.
**fwupd-efi**: tarball releases only. No backported individual patches.
If a tarball release isn't available, ping upstream to test and release one.

**fwupd**: fwupd releases in the matching major series (for example 1.9.x
or 2.0.x) that was already introduced into Ubuntu. This policy addresses microreleases only.

Firmware QA Process
-------------------

When a new version of fwupd or fwupdate is uploaded to -proposed, the
When a new version of fwupd or fwupd-efi is uploaded to -proposed, the
following will be done:

- Test that UEFI capsule updates still work properly on an OEM system
Expand Down