Lubuntu/lubuntu-packaging-guide
4
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document changelogs, start documenting control files

Browse Source
This commit is contained in:
Aaron Rainbolt 2026-01-14 10:29:15 -06:00
parent f11bc5f603
commit bf9356430b
Signed by: arraybolt3
GPG Key ID: A709160D73C79109
1 changed files with 221 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

226
lubuntu-packaging-guide.rst
View File

@ -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
fairly simple package, ``lxqt-about``::
To get an idea of how source trees are structured, we'll start with a fairly
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.