1 files changed, 103 insertions, 0 deletions
diff --git a/debian/README.source b/debian/README.source
new file mode 100644
index 0000000..f98e95b
--- /dev/null
+++ b/debian/README.source
@@ -0,0 +1,103 @@
+firmware-free
+=============
+
+Upstream
+--------
+
+firmware-free is based on the linux-firmware.git repository, which
+does not currently make tarball (or tagged) releases.  Also, most of
+its contents are non-free.
+git://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git
+
+We set the upstream version to the date of the last commit 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.
+
+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 free based on the information in 'WHENCE' and that
+haven't been excluded.
+
+Binary package definition
+-------------------------
+
+The binary package definitions are placed under 'debian/config' and
+written in a format similar to INI files, parsed using the Python
+ConfigParser module
+<https://docs.python.org/3/library/configparser.html>,
+
+The [base] packages field in the top-level 'defines' file lists all
+the binary package names, without the fixed prefix 'firmware-'.
+
+For each binary package, there is a subdirectory with matching name
+(again without the prefix) containing another 'defines' file with
+metadata.  Any non-upstream firmware files are also included in
+these subdirectories.
+
+The script 'debian/bin/check_upstream.py' will list the upstream
+firmware files that are free but not assigned to any binary
+package.
+
+Required metadata:
+
+[base] desc: Short description of related hardware, used in Description
+[base] files: List of files to be included, one per line
+[base] longdesc: Longer description of related hardware and drivers, used in
+                 Description.
+
+Optional metadata:
+
+[base] uri: Upstream URL, used as Homepage and in copyright file.  Not
+            needed if the contents come from linux-firmware.git.
+[base] support: Set to 'initramfs-tools' if update-initramfs should be
+                invoked after installation
+[base] replaces: Used as Replaces field
+[base] conflicts: Used as Conflicts field
+[base] provides: Used as Provides field
+
+Optional per-file metadata:
+
+[<filename>_base] desc: One-line description for this file, used in
+                        package description
+[<filename>_base] version: Verson number for this file, used in package
+                           description
+
+To re-generate debian/control (and other files) based on these
+definitions:
+
+1. Install the current linux-support-<kernelversion> package
+2. Ensure debian/rules.defs has the right value of KERNELVERSION
+3. If the 'orig.tar' archive is not yet available, retrieve it as follows:
+   ``uscan --download-version <upstream-version>`` (<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/')``
+4. Run: debian/rules orig
+5. Run: debian/rules debian/control
+
+To update the current package's changelog with the new upstream version:
+
+1. Run: PYTHONPATH=/usr/share/linux-support-<version>/lib/python \
+            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
+
+ -- Ben Hutchings <benh@debian.org>, Sun, 20 Aug 2023 18:33:40 +0200