ubuntu · j5awry · Apr 30, 2026 · Apr 30, 2026 · Apr 30, 2026 · May 1, 2026
@@ -89,15 +89,13 @@ SRUs <reference-general-requirements>`
 Documentation
 ~~~~~~~~~~~~~
 
-[Insert specifics here: SRU template, what is expected in each section,
-etc]
-
 Documentation must be provided in order to meet our :ref:`public
 documentation requirement <explanation-public-documentation>` as well to
 assist the SRU team to review your upload. This is usually done
 individually in the description area of the bug, for each bug being
 fixed by the SRU, and should follow the :ref:`SRU bug template
-<reference-sru-bug-template>`.
+<reference-sru-bug-template>`. This page contains an annotated template
+explaining requirements and providing examples for each section.
 
 Explicit is better than implicit: if there's anything a reviewer might
 find unexpected, calling it out will help us tell the difference between

@@ -23,8 +23,9 @@ Minimise regression
 Behaviour a user reasonably relies upon that works today must not break
 tomorrow as a result of an update. In a stable release, this includes
 *any* user interface change! Exception: behaviour that we deem buggy
-must necessarily change in order to fix it. [Expand on this]. See `xkcd
+must necessarily change in order to fix it. See `xkcd
 spacebar heater <https://xkcd.com/1172/>`_.
+.. expand the exception with a real world example.
 
 In contrast to pre-release versions, official releases of Ubuntu are
 subject to much wider use, and by a different demographic of users.
@@ -67,4 +68,8 @@ Maintain usefulness
 ~~~~~~~~~~~~~~~~~~~
 
 We make exceptions to keep the distribution useful. E.g. Firefox,
-hardware enablement, Internet protocol [need to expand on this].
+hardware enablement, Internet protocol.
+
+..
+    expand the above section with real examples.
+
@@ -1,7 +1,7 @@
 Standard processes
 ------------------
 
-[this section needs cleaning up]
+.. this section needs cleaning up
 
 -  We'd like the minimum process necessary. It should be clear why any
    process we have is required because of the principles.
@@ -29,8 +29,9 @@ Standard processes
    evidence that this has happened (typically by including the version
    number of the package tested).
 
--  No iterating in stable releases. [Robie needs to explain what he
-   means here]
+-  No iterating in stable releases.
+
+.. [Robie or anyone else needs to explain what they mean here]
 
 .. _explanation-autopkgtest-failures:
 

@@ -25,7 +25,10 @@ and mitigates risk.
 
     [ Test Plan ]
 
-     * detailed instructions how to reproduce the bug
+     * detailed instructions how to reproduce the bug. Instructions should be
+       broken into steps which are clear and actionable.
+
+     * any step that has an expected return, provide the expected returns.
 
      * these should allow someone who is not familiar with the affected
        package to reproduce the bug and verify that the updated package

@@ -0,0 +1,107 @@
+.. _btrfs-progs:
+
+===========
+Btrfs-progs
+===========
+
+Basic Information
+-----------------
+
+* ``btrfs-progs`` is maintained in GitHub and follows the kernel release cycle. [#f1]_
+* ``btrfs-progs`` states:
+
+    “The *btrfs-progs* of version *X.Y* declare support of kernel features of the same version. New progs on old kernel are expected to work, limited only by features provided by the kernel.” [#f2]_
+
+* Releases use tags. As can be seen in the tags, there are no long-term branches, instead continuous moving versions aligning with upstream kernels. [#f3]_
+* Primary functionality of ``btrfs`` is contained in the kernel.
+* For minor releases: “A minor version release may happen in the meantime if there are bug fixes or minor useful improvements queued.” [#f4]_
+
+Autopkgtest
+-----------
+
+As of 20260128, ``btrfs-progs`` does not have autopkgtests. Reverse run-time dependencies are outlined below.
+
+Dependency Analysis
+~~~~~~~~~~~~~~~~~~~
+
+Reverse-Depends
+===============
+
+* ``apt-btrfs-snapshot``: create btrfs snapshots whenever apt is run (universe)
+* ``btrbk``: backup tool for btrfs volumes (universe)
+* ``btrfsd`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x]: daemon for btrfs maintenance (universe)
+* ``btrfsmaintenance``: scripts automating btrfs maintenance tasks (universe)
+* ``calamares-settings-mobian``: calamares + Mobian for small touch screen devices (universe)
+* ``freedom-maker``: FreedomBox image maker. Freedombox is a personal cloud server (universe)
+* ``golang-github-containerd-btrfs-dev`` (src: ``golang-github-containerd-btrfs``): go bindings for btrfs (universe)
+* ``initramfs-tools-devices``: Common initramfs scripts for Ubuntu Core and Classic (universe)
+* ``kiwi-dracut-lib`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x] (src: ``kiwi``): modules for dracut for kiwi image builder
+* ``kiwi-systemdeps-filesystems`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x] (src: ``kiwi``): kiwi image builder host setup helper (universe)
+* ``libblockdev-btrfs3`` (src: ``libblockdev``): library plugin and standalone for btrfs and C++ projects (universe)
+* ``libguestfs0t64`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x] (src: ``libguestfs``): shared library for guest disk image management (universe)
+* ``mkosi``
+* ``ubuntu-server`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x]: meta
+* ``ubuntu-server-minimal`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x]: meta
+* ``ubuntu-server-raspi`` [arm64 armhf]: meta
+
+Reverse-Recommends
+==================
+
+* ``calamares`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x]: alternative graphical installer (universe)
+* ``calamares-extensions`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x]: mobile modules for calamares
+* ``distrobuilder`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x]
+* ``lubuntu-desktop`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x]: meta
+* ``lubuntu-desktop-minimal`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x]: meta
+* ``ntfs2btrfs`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x]: convert ntfs to btrfs (universe)
+* ``ubiquity`` [amd64 amd64v3 arm64 armhf ppc64el riscv64 s390x]: old installer
+
+Reverse-Build-Depends
+=====================
+
+* ``btrfsd``: yet another btrfs daemon for maintenance tasks (universe)
+* ``containerd-app``: daemon to control runc. Runc + containers = can use btrfs
+* ``containerd-stable``: as above
+* ``docker.io-app``: as above, except Docker
+* ``golang-github-containerd-btrfs``: stated above with ``golang-github-containerd-btrfs-dev``
+* ``libguestfs``: stated above with ``libguestfs0t64``
+
+..
+
+Of these dependencies, only ``libblockdev`` provides direct ``btrfs`` testing mounting ``btrfs`` filesystems, manipulating volumes and snapshots, and validating the plugin path from top level to the kernel module. Of the build dependencies, only ``docker.io-app`` contains any reference to ``btrfs``, and it’s somewhat ancillary. Running the ``docker-in-lxd`` tests configure ``lxd`` with a ``btrfs`` backend.
+
+The packages broadly show a need to have matching functionality with the kernel. For image building, container runtimes, and libraries it is important to ensure full-functionality with kernel features. For btrfs-specific maintenance scripts and daemons, stability of the interface is important.
+
+Autopkgtest Requirements and Addition of Tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Btrfs-progs`` needs to have autopkgtests added to be able to be SRU’d safely. Further, passing ``libblockdev`` tests are of high importance.
+
+1. Test installation and upgrade of ``btrfs-progs`` (it’s currently seeded on server, so will likely be in any VM, container, or chroot unless explicitly pruned).
+2. Test basic filesystem operations:
+
+   1. Create a bare partition
+   2. Ensure partition is unmounted
+   3. Mkfs.btrfs the new partition
+   4. ``btrfs check --read-only --force $device``
+   5. Ensure partition is mounted
+   6. Write a bunch of files
+   7. Run ``btrfs filesystem du``, ensure nothing crashes
+   8. Run ``btrfs device stats $device``
+   9. All commands need sudo
+   10. Tests must be run with ``isolation-machine``
+
+The goal of the tests is not to run every command, nor to cover every case. It’s a selection of “low-hanging fruit” that tests that the program is installed and common commands are available. We will not be able to cover all the cases in an autopkgtest, including functions such as subgroups, managing quota, replication, etc.
+
+Tests must be run with the LTS and HWE kernel. Creating a proper dependency graph that ensures these tests are automatically run on upload of any filesystem tool may not be possible. In which case a single case will be covered for any interim bugfix updates, and manual testing against LTS and HWE done on ``btrfs-progs`` updates.
+
+Kernel Testing
+--------------
+
+The Ubuntu Kernel team maintains a test suite that exercises filesystem capabilities. During the coordinated dot release, the kernel team will run these tests against the LTS kernel and the HWE kernel with the new version of ``btrfs-progs`` that has been prepared. Aspirationally, this testing will be done with a package made in a PPA, as there is currently no way to block proposed-migration on an external test. The kernel team will also aid when the new version of any filesystem tool is made available to do similar testing. The Kernel team regularly runs filesystem tests using the version of userspace tools already released, so continuous testing will occur related to kernel updates. Test results from the kernel runs will be posted to the appropriate SRU bugs.
+
+.. rubric:: Footnotes
+
+.. [#f1] https://github.com/kdave/btrfs-progs?tab=readme-ov-file#release-cycle
+.. [#f2] https://github.com/kdave/btrfs-progs?tab=readme-ov-file#feature-compatibility
+.. [#f3] https://github.com/kdave/btrfs-progs/tags
+.. [#f4] https://github.com/kdave/btrfs-progs?tab=readme-ov-file#release-cycle
@@ -27,6 +27,7 @@ Learn more about the criteria to accept a package update, about your responsibil
     special
     package-specific
     historical-removals
+    requirements-closely-coupled-kernel-userspace
 
 Testing and SRU verification
 ----------------------------