FAQ

Revision 7 as of 2022-09-05 12:27:56

Clear message

My unsorted Ubuntu packaging and maintenance FAQ

(that incl. even more - somewhat related - topics)

Help

Terms

Some important terms (with each more info below):

+1 Maintenance

Ubuntu Release Process

* References

* Each Ubuntu release cycle follows a similar pattern, with the phases listed below.

* 8 Phases:

  • Beginning a new Release (toolchain, seeds)
  • Planning (specs, ideas)
  • Merging with Upstream (syncs, merges until Debian Import Freeze)
  • Feature Development (oerlap usually with mergig, spec implementation)
  • Stabilization (Freeze) (greater caution towards release, queued uploads, FFe)
  • Milestones (images for alpha, beta, RC)
  • Finalization (only fixing showstopper/severe bugs, crashes, install issues)
  • Stable Releases (SRU - stable release update process starts)

SRU / Stable Release Update process

SRU Verification

Freeze

Sponsoring / Sponsorship / Sponsors

FFe

  • References:
  • Example:
    • [FFe] [UBUNTU 22.04] ibmca engine with libica = libica.so.4 - sshd dumps core (openssl-ibmca)

      https://bugs.launchpad.net/bugs/1967141 > openssl-ibmca (2.2.3-0ubuntu1) jammy; urgency=medium

    • New upstream release. LP: #1967141
    • The difference between 2.2.2 and 2.2.3 includes just these two fixes:
      • + "PKEY: Fix usage of ECX keys" + "use correct libica for ibmca_mechaList_test" Rather than adding these as quilt patches, raising the package to the bugfix-only version that incl. them is preferable.
    • For "PKEY: Fix usage of ECX keys" a backport of
      • "Fix compilation for OpenSSL 3.0" was needed: d/p/e59cce5-Fix-compilation-for-OpenSSL-3.0.patch
    • For convenience reasons a generated sample config is now included in
      • the package, but also the optional configuration generator Perl script 'ibmca-engine-opensslconfig'.
    • d/control: add dh-autoreconf to Build-Depends to work around a Lintian
      • regression on missing-build-dependency-for-dh-addon

Package Uploads

Proposed migrations

autopkgtests

* it's the uploader's responsibility to make sure the package is in a releasable state and that all the autopkgtests triggered by the upload are either passing or badtested

  • lp-test-ppa from https://git.launchpad.net/~ubuntu-server/+git/ubuntu-helpers offers some help:

    • lp-test-ppa --showurl ppa:kstenerud/postfix-postconf-segfault-1753470 --release bionic
  • The '--showurl' parameter prints out the URL, so that they can be cut-and-paste into email or chat. * using KVM:
  • using LXD:
    • autopkgtest-build-lxd images:ubuntu/impish/amd64
    • autopkgtest -U -s -o dep8-mypackage mypackage/ -- lxd autopkgtest/ubuntu/focal/amd64
  • using a PPA: --setup-commands="sudo add-apt-repository -y -u -s ppa:mylaunchpaduser/focal-mypackage-fixed-something-1234567"
  • on Canonistack (which is closest to real autopkgtests)
    • autopkgtest --no-built-binaries --apt-upgrade --setup-commands setup-testbed --shell-fail systemd_247.3-1ubuntu2.dsc -- ssh -s nova -- --flavor m1.small --image ubuntu/ubuntu-focal-daily-s390x-server-20221023-disk1.img --keyname fheimes_canonistack-bos01
  • by default: est will run against all packages in release plus the new candidate from proposed:

    • '--apt-pocket=proposed=src:<yourpkg>' or '--apt-pocket=proposed=src:srcpkg1,srcpkg2'

  • run against all packages that are in proposed:
    • '--apt-pocket=proposed'
  • in case a test requires a proxy one may add:

    • --env "http_proxy=http://squid.internal:3128" --env "https_proxy=http://squid.internal:3128" --env "no_proxy=127.0.0.1,127.0.1.1,localhost,localdomain,novalocal,internal,archive.ubuntu.com,security.ubuntu.com,ddebs.ubuntu.com,changelogs.ubuntu.com,launchpad.net,10.24.0.0/24"

Phasing / Staging

  • References:
  • Once an package is released to -updates, the update is then phased so that the update is gradually made available to expanding subsets of Ubuntu users.
  • This process allows us to automatically monitor for regressions and halt the update process if any are found. Complete details about the process can be found in a blog post by Brian Murray.

Merge proposals for package updates

  • It's recommended to do a quick self review of your merge proposal for a package update or version bump
  • Initial Review of the diff / debdiff
  • Check the changelog:
    • Contains bug pointer, like '(LP: #1234567)'

    • Proper version change: https://wiki.ubuntu.com/SecurityTeam/UpdatePreparation#Update_the_packaging

    • Proper distribution: not unstable, not a Debian release name
    • Lists ideally all files changed
    • quilt patches with 'fuzz' are not allowed and need to be fixed/refreshed
    • refresh of quilt patches to solve 'offsets' should be at done at max if working on '-devel'
      • (so for PATCHES, not for SRUs) or to fix a fuzz

    • Proper author & email

    • make the changelog clear and crisp - ideally "grep-able" with key words, file names, etc.

  • Following the dep-3 http://dep.debian.net/deps/dep3/ for quilt patches:

    • Description: <short description, required>

      • <long description that can span multiple lines, optional>

      Author: <name and email of author, optional> Origin: <upstream|backport|vendor|other>, <URL, required except if Author is present> Bug: <URL to the upstream bug report if any, implies patch has been forwarded, > Bug-<Vendor>: <URL to the vendor bug report if any, optional> Forwarded: <URL|no|not-needed, useless if you have a Bug field, optional> Applied-Upstream: <version|URL|commit, identifies patches merged upstream, option> Reviewed-by: <name and email of a reviewer, optional> Last-Update: 2021-11-19 <YYYY-MM-DD, last update of the meta-information, option> --- This patch header follows DEP-3: http://dep.debian.net/deps/dep3/

  • Check the commits:
    • Patches / changes are logically split into separate git commits (d/p)
    • in case a package was never touched by Canonical for Ubuntu
      • (hence has no 'ubuntu?' in its version), but now needs to be, the tool 'update-maintainer' tool needs ot be called which will modify debian/control which then needs to be committed as well (as separate commit) (d/control)
    • changelog is usually the last commit (d/changelog)
  • Check the files:
    • Only files inside the debian directory must be modified!
  • Review Template

    • [ https://github.com/canonical/ubuntu-maintainers-handbook/blob/main/MergeProposalReview.md ] The following template may come useful when submitting reviews:

      • Changelog:
        • [ ] old content and logical tag match as expected
        • [ ] changelog entry correct version and targeted codename
        • [ ] changelog entries correct
        • [ ] update-maintainer has been run
      • Actual changes:
        • [ ] no upstream changes to consider
        • [ ] no further upstream version to consider
        • [ ] debian changes look safe
      • Old Delta:
        • [ ] dropped changes are ok to be dropped
        • [ ] nothing else to drop
        • [ ] changes forwarded upstream/debian (if appropriate)
      • New Delta:
        • [ ] no new patches added
        • [ ] patches match what was proposed upstream
        • [ ] patches correctly included in debian/patches/series
        • [ ] patches have correct DEP3 metadata / header (incl. working URL for field Origin)
      • Build/Test:
        • [ ] build is ok
        • [ ] verified PPA package installs/uninstalls
        • [ ] autopkgtest against the PPA package passes
        • [ ] sanity checks test fine
      • Other:
        • [ ] LP bug public
        • [ ] LP bug affects the correct package(s)
  • If there is now everything is prepared:
    • change the MP from "work in progress" to "needs review"
    • (on change to 'needs review' you'll get a notification mail)
    • and check (again) that the correct reviewer is set
    • and check (again) that a 'Related bug(s)' is assigned
    • change the LP bug status to "In Progress"
    • a SRU template was added to the LP bug (not needed for development release patches)
    • subscribe the "ubuntu-sponsors" LP group to the LP bugs (since sponsorship is needed)
    • ask someone to review and sponsor (maybe informally)
    • add a tag for the ubuntu release, like 'focal'
    • crossing fingers that everything is okay ...
  • If the reviewer / sponsor is happy and uploaded the changes,
    • he/she usually adds a comment to the ticket, like: " Thanks. I fixed up a small lintian warning about the changelog entry being longer than 80 chars. Other than that, LGTM. Uploaded. "
  • If the updated package has arrived at the ubuntu release unapproved queue:
  • SRU package upload is stuck
    • In case an SRU package upload is stuck in the upload queue for several days (e.g. 1+ week), join the IRC channel #ubuntu-release and ask the SRU team kindly for having a look at this specific package, by using the tag "ubuntu-sru", ideally adding the URL and ask for approval. But better double check the status before using rmadison:
    • Example, write:
    • Don't forget to be thankful:

      • "@<SRU-team member> many thx (just received the notification ...)"

    • So use the IRC channel: #ubuntu-release
      • Highlight with "ubuntu-sru" - the SRU team member should have a notification enabled for this keyword (similar to "ubuntu-archive", "ubuntu-release", "ubuntu-sponsors", ...)
  • Sometimes it might be needed to directly ping the SRU team member that's on duty directly
  • In case of package for the development release that is stuck in the upload queue,
    • use again #ubuntu-release (not necessarily #ubuntu-devel), since what's basically needed is approval from someone from the RT (release-team) or AA (archive-admins) to sign this up, and those hang out in '#-release'.

Package versioning

Patch / Fix

Packaging

  • Rename file during Debian install

    • possible with dh >= 9 and dh-exec make the .install file executable (chmod a+x debian/package.install) add '#!/usr/bin/dh-exec' to the top of debian/package.install and use "source => dest", like this: #!/usr/bin/dh-exec debian/default.conf => /etc/my-package/start.conf

  • Upload issues with dput:
    • Sometimes dput does not work for me in case VPN is active. If a dput upload hangs, retry with company VPN disabled.
  • Check source and deb packages with lintian using:
    • 'lintian -EvIL +pedantic' Make sure that at least all errors are solved, and ideally the warning, too.
  • "${shlibs:Depends}" in debian/control is expanded to:
    • ldd on binaries + dpkg -S on the library files (+ symbols files for finer-grained dependency)
  • In case it's not possible to git-ubuntu clone a package, like:
  • Sometimes the Origin URL of a quilt DEP3 header, that usually points to the upstream commit,

New packages

Autobuilders / Builds

Sync / Merge

  • References:
  • General

    • A sync copies a source package verbatim from an external repository into Ubuntu, overwriting any package of the same name. This is used when a newer version of it is available, and should be included in Ubuntu, and happens automatically during some phases of the release cycle. To request a sync, follow the SyncRequestProcess.

    • A merge is a three-way merge of a package which originated in an external repository. This is used when there is a newer version available from the external repository, but the package has also been modified (branched) in Ubuntu. Merge-o-Matic assists with this work, and the Merging page explains how and when to merge. Packages which are maintained in Bazaar can and should be merged using Bazaar itself.
    • Merge (as in ubuntu-maintainers-handbook)
      • Server team does merges using git-ubuntu - similar to a git rebase, where commits from one point are replayed on top of another.
      • also splitting larger commits into smaller logical units,
        • one commit per logical unit (per bug/fix, d/changelog, d/c) (old-style commits that lumped multiple changes)
        • Start a rebase: git rebase -i lp1234567/old/debian
        • Change the commit(s) you're going to split from pick to edit.
        • git reset to get your changes back: git reset HEAD^
        • Now add the commits of a logical unit each, let's say some patches, d/rules, d/control, d changelog
        • and end the rebase with 'git rebase --continue'
        • add tag split (git ubuntu tag --split --bug 1234567)
      • harmonizing d/changelog commits into two commits: a changelog merge and a reconstruction.
  • Sync (as in ubuntu-maintainers-handbook)
    • "For other sync situations, you can review this. Outside of the server team process the common way is to request for an explicit sync via filling a Launchpad Bug or using the 'requestsync' tool."

      https://manpages.ubuntu.com/manpages/impish/man1/requestsync.1.html in case one has permissions to upload the package to Ubuntu: 'syncpackage' (copy source packages from Debian to Ubuntu)

  • merge: debdiff of NEW Debian package and NEW Ubuntu package
  • some general MERGE/SYNC notes to remember:
    • always to a test build (e.g. in PPA) on all relevant architectures (as usual)
    • if tests are available, run them as well
    • also do an package install and update test

    • and check the package content (dpkg -c <package>)

    • look for upstream bugs that can be fixed at the same time

    • check for any "reverse-depends -a source src:<package>" (esp. with libs)

      • and test build them as well, pointing to the <package> test PPA (or using the same)

    • do the source package build using -v<previous version>, like:

      • dpkg-buildpackage -S -d -v7.6.0-4ubuntu1 --sign-key=... this causes the 'in-between changelog items' to appear in the .changes file (means all changelog entries from previous to new version)
    • make sure the LP bug for the merge is referenced in the changelog
      • (since lot's of things are needed to create and populate the LP bug, I start the work w/o having a LP bug number; so don't forget to add it later!)
    • if working based on the Merge-o-matic files there is usually a proposed changelog file
      • either update this properly or create a new/current entry using 'dch -i'
      • check if the version is correct (MERGES and SYNCS aren't SRUs!)
      • update the version from UNSTABLE (or so) to the current development release (kinetic)
      • update the urgency (should usually be medium, and not low as in the 'mom' template)
      • if reusing the 'mom' template overwrite the mom mail with yours
        • and update the date to the current one! (not needed is using 'dch -i')
  • Examples for MERGE:
    • 'ferret-vis' - MERGE
      • LP#1986565 - "Please merge ferret-viz 7.6.0-5 into kinetic"

        https://bugs.launchpad.net/bugs/1986565 ferret-vis (7.6.0-5ubuntu1) kinetic; urgency=low

      • Merge from Debian unstable, remaining change:
        • + Build without lto. lto-disabled-list can't be used (d/rules), because
          • dpkg-buildflags is called after changing the package base directory.
    • 'libgcrypt20' - MERGE
      • LP#1974277 - "Please merge libgcrypt20 1.10.1-2 (main) from Debian unstable (main)"

        https://bugs.launchpad.net/bugs/1974277 > libgcrypt20 (1.10.1-2ubuntu1) kinetic; urgency=low

      • Merge from Debian unstable. (LP: #1974277) Remaining changes:
        • + d/p/disable_fips_enabled_read.patch
          • Disable the library reading /proc/sys/crypto/fips_enabled file and going into FIPS mode. libgcrypt is not a FIPS certified library.
      • Removed d/p/0001-Always-include-config.h-in-cipher-assembly-codes.patch
        • since it's already included in the new version.
      • Removed d/p/0001-poly1305-fix-building-with-arm-linux-gnueabihf-gcc-1.patch
        • since it's already included in the new version.
      • Refreshed d/p/12_lessdeps_libgcrypt-config.diff
        • and d/p/disable_fips_enabled_read.patch due to offsets.

        https://launchpadlibrarian.net/602209655/debdiff_libgcrypt20_of_Debian_1.10.1-2_and_Ubuntu_1.10.1-2ubuntu1.patch

    • 'atlas' - MERGE
  • Examples for SYNC:

Backports

  • References:
  • Backports work 'roughly' similarly to syncs, but have somewhat different requirements.
  • backports have a tilde ('~') in their version string, like: 1.2.3-3ubuntu1~20.04.1

Transition

  • If build dependencies (e.g. of a library) change significantly,
    • or are updated with a new version that comes with API/ABI changes, a rebuild of all packages that need that lib as build dependency is needed (as well as testing, e.g. autopkgtests).
  • To find all reverse dependencies use: reverse-depends -a source src:libica
  • Example:
    • LP#1959421 - "[22.04 FEAT] Upgrade libica to latest version (crypto) (v4.0)" incl. transition

      https://bugs.launchpad.net/bugs/1959421 > libica (4.0.1-0ubuntu1) jammy; urgency=medium

    • New upstream release LP: #1959421
    • transition from libica3 to libica4
      • + adjust d/control + migrate d/libica3.* to d/libica4.* + extended symbols file
    • adjusting d/copyright
      • + change tabs to spaces + update relevant copyright years

MIR (main inclusion report)

Package Removal

  • References:
  • Only upon request, via LP bug tht must include:
    • which Ubuntu release to remove it from
    • remove both the source package and all binary packages?
    • why they should be removed
    • confirm that the binary packages have no rdepends (means no other package depends on them)
  • if help if needed on the decision to whether a package should be removed or not,
    • start a discussion on the 'ubuntu-devel' mailing

NBS

  • References:
  • Binary packages that are not built from any source (anymore)
  • some reasons for such cases:
    • a library gets a new SONAME (libfoo[n+1]) (due to an update),
      • the previous version built libfoo[n]
    • a package gets renamed by upstream and the renaming is reflected in the package name change
  • such packages are not automatically removed from the archive,
    • since they still have reverse dependencies (packages depending on them)
  • Sometimes one NBS package will depend on another, which can confuse a transition.
  • In case a package has an alternate dependency, it will still show (but doesn't always need fixing).
  • Remember that NBS removals are manual, which can confuse the results.

Symbols

Seeds

Bileto / former "CI Train"

Upload rights

Kernel bug fixing / pathing

  • References:
  • cherry-pick lines:
    • (cherry picked from commit de5012b41e5c900a8a3875c7a825394c5f624c05 linux-next) or just: (cherry picked from commit de5012b41e5c900a8a3875c7a825394c5f624c05)
  • backported lines:
    • (backported from commit 1a82f6ab23659aa01a796d9d444ec9cc63ded26c linux-next) or just: (backported from commit 3d787b392d169d4a2e3aee6ac6dfd6ec39722cf2) [Frank Heimes: Resolve minor conflict due to additional includes.]
  • In both cases add:
  • for kernel pull-requests:
    • for backports (applied with 'git am'):

      • + <blank line> + <commit name> + <blank line> + ADD a "From: <original author>" line + <blank line> + BugLink: https://bugs.launchpad.net/bugs/1234567 + <blank line> + ... + (backported from commit 012a224e1fa31fc256aab921f691598e03db6018) + [Frank Heimes: Backport needs to use primary address space.] + Signed-off-by: Frank Heimes <frank.heimes@canonical.com>

      for cherrypicks:

Bugs / Triage

Further reading/references: