Document changelogs, start documenting control files

lubuntu-packaging-guide.rst

@@ -30,10 +30,12 @@ how they work internally. Source packages are bundles of source code with
 Debian packaging metadata. This metadata describes (among other things) how to
 build the package, and where the files it installs should go. *Building* a
 source package will create one or more binary packages, along with some other
-files that we'll describe as we go.
+files that we'll describe as we go. Source packages are themselves generated
+from source *trees* (directories full of source code), which is what packagers
+work with most of the time.
 
-To get an idea of how source packages are structured, we'll start with a
+To get an idea of how source trees are structured, we'll start with a fairly
-fairly simple package, ``lxqt-about``::
+simple packaged application, ``lxqt-about``::
 
     aaron@pkg-builder:~/vmshare/pkg/lxqt-about$ tree
     .
@@ -1525,7 +1527,7 @@ Miscellaneous useful things to know about Git
   enter what Git calls "detached HEAD state". This means that any commits you
   make will not be integrated into any existing branch, and if you check
   something else out later, you'll probably have a hard time finding those
-  commits later. If you decide you want to keep the changes you've made, use
+  commits. If you decide you want to keep the changes you've made, use
   ``git switch -c new-branch-name`` to make a new branch with any changes
   you've made so far.
 * As a general rule, do not use force-push unless you're fixing commits you
@@ -1536,4 +1538,218 @@ Miscellaneous useful things to know about Git
 Foundations of Debian packaging
 -------------------------------
 
-TODO
+Finally, we're to the point where we can start doing some real packaging!
+There's a lot to take in here, so expect to use this section as a reference to
+begin with.
+
+Above, when we discussed the high-level overview of a Debian package, we gave
+a list of important files in Debian packaging, and what their purpose is. In
+this section, we'll look much closer at each individual file, how it's
+formatted, and how to modify it.
+
+The changelog
+^^^^^^^^^^^^^
+
+The changelog records all of the changes that have been made to the package as
+maintainers update it. It also defines which *distribution* (usually a version
+of Ubuntu) that the package is designed for, identifies the people who made
+changes to the package, notes when they changed the package, and defines what
+*version* the package is.
+
+Let's look at part of the changelog for the ``lxqt-about`` package::
+
+    lxqt-about (2.2.0-0ubuntu1) questing; urgency=medium
+
+      * New upstream release.
+        - Update build dependencies.
+      * Update copyright file.
+      * Update Standards-Version to 4.7.2, no changes needed.
+
+     -- Aaron Rainbolt <arraybolt3@ubuntu.com>  Thu, 31 Jul 2025 16:14:12 -0500
+
+    lxqt-about (2.1.0-0ubuntu3) plucky; urgency=medium
+
+      * Update Standards-Version to 4.7.1, no changes needed.
+
+     -- Simon Quigley <tsimonq2@ubuntu.com>  Fri, 21 Feb 2025 16:41:21 -0600
+
+There's a lot of info here, so let's break this down a bit further::
+
+    (Changelog stanza)  (Package name)  (Package version)  (Target distro)
+    |                   |               |                  |
+    |        +----------+ +-------------+ +----------------+
+    +---\    v            v               v
+    |   lxqt-about (2.2.0-0ubuntu1) questing; urgency=medium  <--(Upload urgency)
+    |
+    |     * New upstream release.         <--(Changelog entry)
+    |       - Update build dependencies.  <--(Changelog entry sub-point)
+    |     * Update copyright file.        <--(Changelog entry)
+    |     * Update Standards-Version to 4.7.2, no changes needed.  <--(Changelog entry)
+    |
+    |    -- Aaron Rainbolt <arraybolt3@ubuntu.com>  Thu, 31 Jul 2025 16:14:12 -0500
+    |       \------------/            ^             \-----------------------------/
+    |    +--+             +-----------+     +-------+
+    |    |                |                 |
+    |    (Packager name)  (Packager email)  (Time of upload)
+    +---/
+
+    Changelog stanza
+    |
+    +---\
+    |   lxqt-about (2.1.0-0ubuntu3) plucky; urgency=medium
+    |
+    |     * Update Standards-Version to 4.7.1, no changes needed.
+    |
+    |    -- Simon Quigley <tsimonq2@ubuntu.com>  Fri, 21 Feb 2025 16:41:21 -0600
+    +---/
+
+Let's go over what each of these things are.
+
+* A changelog *stanza* is a unit of changelog information corresponding to one
+  version of a package. For instance, in the map above, all of the bits of
+  data in the top-most changelog entry corresponds to lxqt-about version
+  2.2.0-0ubuntu1.
+* The package name is the name of the *source* package. Oftentimes one of the
+  binary packages produced by a source package will have the same name,
+  although this is not guaranteed.
+* The package version is the version of the source package and all binary
+  packages produced from it. In this example, the ``lxqt-about`` package is at
+  version 2.2.0-0ubuntu1, and when we build it, all of the binary packages
+  built from it will have that same version.
+* The target distro specifies what OS this package is intended to be installed
+  on. In this changelog entry, ``lxqt-about`` version 2.2.0-0ubuntu1 is
+  intended to run on Ubuntu 25.10 (codenamed "Questing Quokka", and here
+  specified as simply "questing").
+* The upload urgency is generally not used in Ubuntu. In Debian, it's used to
+  control "migration speed" for managing Debian Unstable and Debian Testing,
+  but Ubuntu's migration system works in a substantially different way and
+  doesn't use this field. We'll look at this closer later on.
+* Changelog entries specify what was done to the package. Each entry should
+  correspond to a single logical change in the package.
+* Sometimes, you'll want to go into more detail about a particular change. You
+  can use sub-points for this.
+* The name, email, and time of upload fields are relatively self-explanatory.
+  The tools you'll use for working with the changelog will fill these in for
+  you.
+
+Let's try making a change to the changelog. Ensure the ``lubuntu-dev`` window
+is open and the VM is running, then open QTerminal and change to the
+``lxqt-about-packaging`` directory::
+
+    cd $HOME/vmshare/pkg/lxqt-about-packaging
+
+Now that we're here, let's create a new changelog stanza. Run ``dch -i`` to
+do this. If you're running this for the first time and haven't selected a
+terminal-based text editor previously, you'll be asked to select an editor. If
+you know how to use Vim, it's best to pick ``vim.basic`` or ``vim.nox`` here,
+otherwise ``nano`` is a good choice.
+
+At this point, you should see the changelog open in the text editor, with text
+similar to the following displayed at the top::
+
+    lxqt-about (2.2.0-0ubuntu2) UNRELEASED; urgency=medium
+
+      *
+
+     -- Your Name <name@example.com>  Wed, 14 Jan 2026 09:53:46 -0600
+
+As we can see, ``dch`` has generated an entire template changelog for us.
+There are a couple things worthy of note here:
+
+* The distribution specified is ``UNRELEASED``. This is a special value that
+  means "the changes listed in this changelog entry haven't been uploaded
+  yet". You will need to change this eventually, we'll cover how later.
+* The version number is updated by simply incrementing it in the most
+  intuitive way possible. While handy in some situations, usually the version
+  number ``dch`` puts here will be wrong. Version numbers require some care to
+  get right, we'll look at this in more detail later.
+
+Let's exit the text editor without saving anything. ``dch`` will report
+``dch: debian/changelog unmodified; exiting.`` This means that the new stanza
+created by ``dch`` was discarded entirely. This is useful, since it means if
+you use the ``dch`` command wrong, you can just close the file without saving
+to undo whatever changes it automatically makes again.
+
+Now let's create a changelog stanza and put something into it. Run ``dch -i``
+again, then ensure there is a single space between the ``*`` character and the
+beginning of the text you type. Then type ``Test change`` here. The changelog
+should look like this when you're done::
+
+    lxqt-about (2.2.0-0ubuntu2) UNRELEASED; urgency=medium
+
+      * Test change
+
+     -- Your Name <name@example.com>  Wed, 14 Jan 2026 09:53:46 -0600
+
+Now save the file and close it. You'll notice ``dch`` doesn't say anything
+about the changelog being unmodified. If you look at the start of the
+changelog with ``head debian/changelog``, you'll see your new changelog stanza
+is there.
+
+If you want to open the changelog without changing anything, run ``dch -e``.
+This is a simpler (and in some ways safer) way to open and edit the changelog
+than running ``vim debian/changelog`` or similar.
+
+A lot of the time, you'll probably want to add a new changelog entry to the
+topmost changelog stanza, rather than creating an entirely new stanza. Use
+``dch -a`` for this. A new changelog entry will be created at the bottom of
+the list of entries. (If you want to create a sub-point underneath a changelog
+entry, it's easiest to just type it in manually. Changelogs are just text
+files, so anything ``dch`` does can be done manually too, and you can do
+things ``dch`` isn't capable of too.)
+
+The last ``dch`` command you'll end up using a lot is ``dch -r``. This
+"finalizes the changelog for a release". In concrete terms, it will change the
+distro field from ``UNRELEASED`` to the name of the OS you're doing packaging
+on (in this case, ``resolute``), and it will update the date and time of the
+changelog entry to the current date and time.
+
+The control file
+^^^^^^^^^^^^^^^^
+
+Control files are slightly confusing, since there are several different things
+control files can be used for, and they contain slightly different bits of
+data depending on the use case. We're going to focus on only one type of
+control file here, the kind used in source packages.
+
+The control file for ``lxqt-about`` looks like this::
+
+    Source: lxqt-about
+    Maintainer: Lubuntu Developers <lubuntu-devel@lists.ubuntu.com>
+    Original-Maintainer: LXQt Packaging Team <pkg-lxqt-devel@lists.alioth.debian.org>
+    Uploaders: Alf Gaida <agaida@siduction.org>,
+               ChangZhuo Chen (陳昌倬) <czchen@debian.org>,
+               Andrew Lee (李健秋) <ajqlee@debian.org>
+    Section: x11
+    Priority: optional
+    Build-Depends: debhelper-compat (= 13),
+                   libkf6windowsystem-dev,
+                   liblxqt2-dev (>= 2.2.0),
+                   libx11-dev,
+                   qt6-svg-dev
+    Standards-Version: 4.7.2
+    Vcs-Browser: https://git.lubuntu.me/Lubuntu/lxqt-about-packaging
+    Vcs-Git: https://git.lubuntu.me/Lubuntu/lxqt-about-packaging.git
+    Debian-Vcs-Browser: https://salsa.debian.org/lxqt-team/lxqt-about
+    Debian-Vcs-Git: https://salsa.debian.org/lxqt-team/lxqt-about.git
+    Homepage: https://github.com/lxqt/lxqt-about
+    Rules-Requires-Root: no
+
+    Package: lxqt-about
+    Architecture: any
+    Depends: ${misc:Depends}, ${shlibs:Depends}
+    Recommends: lxqt-about-l10n, lxqt-qtplugin
+    Description: About screen for LXQt
+     The about screen for LXQt
+     .
+     This package contain the LXQt about screen.
+
+    Package: lxqt-about-l10n
+    Architecture: all
+    Multi-Arch: foreign
+    Section: localization
+    Depends: qt6-translations-l10n, ${misc:Depends}
+    Description: Language package for lxqt-about
+     The about screen for LXQt
+     .
+     This package contains the l10n files needed by the lxqt-about.