firmware-nonfree
================

Upstream
--------

firmware-nonfree is based on the linux-firmware.git repository, which
now does make tarball (or tagged) releases in the form 'CCYYMMDD'.
Also, some of its contents are not clearly redistributable, and some are
obsolete for Debian's purposes.
https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git

We set the upstream version to the last tag and use uscan to generate
a tarball from upstream git.  The Files-Excluded field in 'debian/copyright'
lists file patterns that should be excluded from the tarball.

We also pull module information from Linux binary packages.  To update
this information, run:

    debian/bin/update-modinfo

You can optionally pass a specific kernel release string or directory
in which to look for modules.

We copy the debian_linux Python package from src:linux.  To update it,
run:

    debian/bin/update-python-lib <linux-package-dir>

Licences
--------

The upstream source includes the file 'WHENCE' which lists the licence
and any source code for each file.  The script
'debian/bin/check_upstream.py' will warn about any files that aren't
recognised to be distributable based on the information in 'WHENCE'
and that haven't been excluded.

Each binary package is assumed to have a different licence(s).  The
installed 'copyright' file is taken from the 'LICENSE' file in its
subdirectory.

Some firmware redistribution licences require us to prompt the user to
accept an EULA.  In this case, add a '[package.eula]' subsection as
described below.

Binary package definition
-------------------------

The binary package definitions are written in TOML format in
'debian/config/defines.toml'.

For each binary package, there is a '[[package]]' section with
the package name (without the 'firmware-' prefix) and metadata.

The script 'debian/bin/check_upstream.py' will list the upstream
firmware files that are non-free but not assigned to any binary
package.

Required metadata:

desc: Short description of related hardware, used in Description
files: List of files to be included, one per line
longdesc: Longer description of related hardware and drivers, used in
          Description.

Optional metadata:

uri: Upstream URL, used as Homepage and in copyright file.  Not
     needed if the contents come from linux-firmware.git.
support: List of support features needed.  Include 'initramfs-tools'
         if update-initramfs should be invoked after installation.
replaces: Used as Replaces field
conflicts: Used as Conflicts field
provides: Used as Provides field

If a EULA applies, there is an additional '[package.eula]' subsection
with the following required metadata:

title: Title of the EULA
text: Full text of the EULA

To re-generate debian/control (and other files) based on these
definitions:

1. If the 'orig.tar' archive is not yet available, retrieve it as follows:

   uscan --download-version <upstream-version>

   Where '<upstream-version>' is f.e. '20230210'.
   To retrieve <upstream-version> programmatically, use f.e. this:

   $(head -n1 debian/changelog | sed 's/.*\([[:digit:]]\{8\}\).*/\1/')

   Combined that results in:

   uscan --download-version $(head -n1 debian/changelog | sed 's/.*\([[:digit:]]\{8\}\).*/\1/')

2. Run: debian/rules orig
3. Run: debian/rules debian/control

To update the current package's changelog with the new upstream version:

1. Run: debian/bin/release-update /path/to/linux-firmware-repository

   This will update debian/changelog with the changes added between
   the commit of the current package version and the HEAD commit found in the
   linux firmware repository, passed as argument.

2. Remove entries regarding firmwares files not packaged

Additional and replacement files
--------------------------------

The debian/added-firmware/ directory functions as an overlay for the
files (and symlinks) provided by upstream.

Occasionally we need to fix a regression by downgrading the firmware.
Since we cannot patch binaries, the old version should be included in
this directory.

For historical reasons, we add some files that were never
included upstream in the firmware-{ipw2x00,ivtv,libertas} packages.
No more such additions should be made in future.

 -- Ben Hutchings <benh@debian.org> Thu, 02 Apr 2026 20:12:42 +0200
