Title: Recommended layout for Git packaging repositories
DEP: 14
State: CANDIDATE
Date: 2020-11-29
Drivers: Raphaël Hertzog <hertzog@debian.org>
URL: https://dep-team.pages.debian.net/deps/dep14/
Source: https://salsa.debian.org/dep-team/deps/-/blob/master/web/deps/dep14.mdwn
Abstract:
 Recommended naming conventions in Git repositories used
 to maintain Debian packages

Introduction

This is a proposal to harmonize the layout of Git repositories used to maintain Debian packages. The goals are multiple:

Scope

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).

Generic principles

Vendor namespaces

Each "vendor" uses its own namespace for its packaging related Git branches and tags: debian/* for Debian, ubuntu/* for Ubuntu, and so on.

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 by setting DEB_VENDOR in their environment (provided that the vendor information does exist in /etc/dpkg/origins/).

If 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.

Version mangling

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:

This can be expressed concisely in the following Perl5 statements:

 y/:~/%_/;
 s/\.(?=\.|$|lock$)/.#/g;

The reverse transformation is:

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 in either a <vendor>/latest or <vendor>/<suite> branch, where <suite> is the suite name of the target distribution. Coexistence of <vendor>/latest and <vendor>/<suite> branches is accepted only if the latter are short-lived, i.e. they exist only until they are merged into <vendor>/latest or until the version in the target distribution is replaced by the version in <vendor>/latest.

In Debian this means that uploads to unstable and experimental should be prepared either in the debian/latest branch or respectively in the debian/unstable and debian/experimental branches.

In the interest of homogeneity and of clarity, for the development branches we recommend the <vendor>/<suite> scheme over <vendor>/<codename> as it better conveys its special nature as opposed to other branches named after codenames which are used for stable releases.

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 like git symbolic-ref HEAD refs/heads/debian/latest 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/jessie, debian/wheezy, 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 wheezy-security or wheezy-proposed-updates are prepared on the debian/wheezy branch. Shall there be a need to manage different versions of the packages in both repositories, then the branches debian/wheezy-security and debian/wheezy-updates 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 upstream/latest 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 in a 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 upstream 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>, <version> and v<version>.

The 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 rules.

About pristine-tar

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 pristine-tar branch.

Native packages

The above conventions mainly cater to the case where the upstream developers and the package maintainers are not the same set of persons.

By contrast, this section applies to native packages where upstream is Debian (or one of its derivatives) and where the packaging and upstream source code are managed in the same branch(es).

In that specific situation, the upstream vendor should not use the usual <vendor>/ prefix for their branches and tags (but all others vendors should do so) and they also don't have to follow the usual naming conventions for packaging branches (although they are free to do so if they wish). However the default branch of the repository (as pointed by the HEAD reference) should be a development branch.

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 associated upstream/* branches are irrelevant too. Note that even if the upstream vendor ships the package as a native package, the downstream vendors can still 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 source package.

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.

Other recommendations

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 upstream sources are really huge and contains mostly non-patchable data), you can do so but you should then document this in 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.

Managing debian/changelog

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 Git commit.

Helper tools should however configure the Git repository so that merges of the debian/changelog file are handled by dpkg-mergechangelogs as this will make it much easier to merge between different packaging branches.

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. foo-1.0 and bar-2.0), you should probably also consider embedding the name in the tags used for your package releases.

Changes