Title: Recommended layout for Git packaging repositories DEP: 14 State: DRAFT Date: 2016-11-09 Drivers: Raphael Hertzog <firstname.lastname@example.org> URL: http://dep.debian.net/deps/dep14 Source: http://anonscm.debian.org/viewvc/dep/web/deps/dep14.mdwn Abstract: Recommended naming conventions in Git repositories used to maintain Debian packages
This is a proposal to harmonize the layout of Git repositories used to maintain Debian packages. The goals are multiple:
making it easier for Debian and its derivatives to build upon their respective Git repositories (with the possibility to share a common one in some cases)
make it easier to switch between various git packaging helper tools. Even if all the tools don't implement the same worflow, they could at least use the same naming conventions for the same things (Debian/upstream release tags, default packaging branch, etc.).
This proposal defines naming conventions for various Git branches and Git tags that can be useful when doing Debian packaging work. The hope is that maintainers of git packaging helper tools will adopt those naming conventions (in the default configuration of their tools).
Each "vendor" uses its own namespace for its packaging related
Git branches and tags:
debian/* for Debian,
ubuntu/* for Ubuntu, and
Helper tools should usually rely on the output of
dpkg-vendor --query vendor
to find out the name of the current vendor. The retrieved string must be
converted to lower case. This allows users to override the current vendor
DEB_VENDOR in their environment (provided that the vendor
information does exist in
dpkg-vendor is not available, then they should assume "debian" is the
current vendor. Helper tools can also offer a command-line option to
override the current vendor if they desire.
When a Git tag needs to refer to a specific version of a Debian package, the Debian version needs to be mangled to cope with Git's restrictions. This mangling is deterministic and reversible:
- Each colon (
:) is replaced with a percent (
- Each tilde (
~) is replaced with an underscore (
- A hash (
#) is inserted between each pair of adjacent dots (
- A hash (
#) is appended if the last character is a dot (
- If the version ends in precisely
k, lowercase, at the end of the version), a hash (
#) is inserted after the dot, giving
This can be expressed concisely in the following Perl5 statements:
The reverse transformation is:
- Each percent (
%) is replaced with a colon (
- Each underscore (
_) is replaced with a tilde (
- Each hash (
#) is deleted
Packaging branches and tags
In general, packaging branches should be named according to the codename of the target distribution. We differentiate however the case of development releases from other releases.
For development releases
Packages uploaded to the current development release should be prepared
However, when multiple development releases are regularly used (for
experimental in Debian), it is also accepted to
name the branches according to the codename or the suite name of the
target distribution (aka
debian/experimental). Those branches can be short-lived (i.e. they exist
only until they are merged into
<vendor>/master or until the version in
the associated repository is replaced by the version in
or they can be permanent (in which case
<vendor>/master should not
NOTE: If the Git repository listed in debian/control's
Vcs-Git field does
not indicate an explicit branch (with the
-b <branch> suffix) then it should
have its HEAD point to the branch where new upstream versions are being
packaged (that is one of the branches associated to a development release).
The helper tools that do create those repositories should use a command
git symbolic-ref HEAD refs/heads/debian/master to update HEAD
to point to the desired branch.
For stable releases
When a package targets any release that is not one of the usual
development releases (i.e. stable releases or a frozen development
release), it should be prepared in a branch named with the codename of the
target distribution. In the case of Debian, that means for example
debian/wheezy-backports, etc. We
specifically avoid "suite" names because those tend to evolve over time
("stable" becomes "oldstable" and so on).
Security updates and stable updates are expected to be handled on
the branch of the associated distribution. For example, in the case of
Debian, uploads to
are prepared on the
debian/wheezy branch. Shall there be a need to
manage different versions of the packages in both repositories, then
can be used.
Tagging package releases
When releasing a Debian package, the packager should create and push
a (preferably signed) tag named
<vendor>/<version>. For example, a
Debian maintainer releasing a package with version 2:1.2~rc1-1 would
create a tag named
debian/2%1.2_rc1-1 whereas an Ubuntu packager
releasing a package with version 1.3-0ubuntu1 would use
ubuntu/1.3-0ubuntu1. The tags should point to the exact commit that was
used to build the corresponding upload.
Managing upstream sources
Importing upstream release tarballs in Git
If the Git workflow in use imports the upstream sources from released
tarballs, this should be done under the "upstream" namespace. By default,
the latest upstream version should be imported in the
branch and when packages for multiple upstream versions are maintained
concurrently, one should create as many upstream branches as required.
Their name should be based on the major upstream version tracked:
for example when upstream maintains a stable 1.2 branch and releases
1.2.x minor releases in that branch, those releases should be imported
upstream/1.2.x branch (the ".x" suffix makes it clear that we are
referring to a branch and not to the tag corresponding the upsteam 1.2
release). If the upstream developers use codenames to refer to their
releases, the upstream branches can be named according to those codenames.
Helper tools should detect when the upstream version imported is lower
than the latest version available in
upstream/latest and should offer
either to create a new branch (based on the highest version available in
the history that is still smaller than the imported version) or to pick
another pre-existing upstream branch.
Importing upstream releases from Git tags
When the packaging branches are directly based on the upstream Git branches, upstream usually also provide proper Git tags that can be reused for official releases.
If helper tools have to identify the upstream commit corresponding to a
given upstream release, they should be able to find it out by looking up
the following Git tags:
upstream/<version> tag would be created by the package maintainer
when needed: for example when it does a release based on a Git snapshot or
when the tag naming scheme used by upstream is not following the above
If the package maintainers use the pristine-tar tool to efficiently store
a byte-for-byte copy of the upstream tarballs, this should be done in the
The above conventions mainly cater to the case where the upstream developers and the package maintainers are not the same set of persons.
When upstream is Debian (or one of its derivative), the upstream vendor
should not use the usual
<vendor>/ prefix (but all others vendors should
do so). The main development branch can be named
master instead of
the codename of the target distribution (although you are free to still
use the codename if you wish so).
When the package is shipped as a native source package (i.e. a single
tarball with no differentiation of the upstream sources and of the
packaging files), the concept of "upstream sources" is irrelevant and the
upstream/* branches are irrelevant too. Note that even if the
upstream vendor ships the package as a native package, the downstream
vendors can still can opt to package it in a non-native way.
Patch queue tags
A patch queue branch is a (possibly temporary) branch used to define the
set of upstream changes that the package will contain, its content is
generally used to later update
debian/patches in the resulting
Helper tools that want to store a copy of the "patch queues branches" for
released versions of the packages should create a tag named
<vendor>/patches/<version>. That tag should usually point to the
upstream branch with vendor patches applied on top of it.
This sections ventures a bit outside of the topic of naming conventions with some further suggestions for package maintainers and developers of helper tools.
What to store in the packaging branches
It is recommended that the packaging branches contain both the upstream
sources and the Debian packaging. Users who have cloned the repository
should be able to run
dpkg-buildpackage -b -us -uc without doing
anything else (assuming they have the required build dependencies).
It is also important so that contributors are able to use the tool of their choice to update the debian/patches quilt series: multiple helper tools need the upstream sources in Git to manage this patch series as a Git branch.
When you have good reasons to only store the
debian packaging directory
(for example when the uptream sources are really huge and contains mostly
non-patchable data), you can do so but you should then document
debian/README.source along with some explanations of the tool
to use to build the package.
About repacked upstream sources
When the upstream sources needs to be repacked (for example to drop some
non-DFSG compliant files), then the branches and tags under the
upstream/ prefix should actually contain the repacked sources.
How the problematic files are pruned does not matter. What matters is that
what is stored in the
upstream/* namespace are the sources that package
maintainers are effectively using.
This DEP makes no specific recommendation on how to manage the Debian
changelog. Some maintainers like to use tools like
gbp dch to generate
the changelog based on Git commit notices, others edit the file manually
and use tools like
debcommit to reuse the changelog entry in the
Helper tools should however configure the Git repository so that merges
debian/changelog file are handled by
this will make it much easier to merge between different packaging
When to not follow the above recommendations
Most of the recommendations in this document assume that the upstream developers use their Git repository in a traditional way: one software per repository and creating tags for released versions.
When the upstream diverge from those conventions, you are entitled
to use your common sense and adapt those recommendations accordingly.
For example, if upstream tags contain the software name (e.g.
bar-2.0), you should probably also consider embedding
the name in the tags used for your package releases.
- 2014-11-05: Initial draft by Raphaël Hertzog.
- 2016-11-09: Extended version mangling to troublesome dots -- Ian Jackson.