RFC: DEP-14: Recommended layout for Git packaging repositories
Hello,
following the initial discussion we had in August
(https://lists.debian.org/debian-devel/2014/08/thrd2.html#00499), I have
written a first draft of the Debian Enhancement Proposal that I suggested.
It's now online at http://dep.debian.net/deps/dep14 and also attached
below so that you can easily reply and comment.
I have left one question where I have had conflicting feedback
and I'm not sure what's best. Thus I will welcome a larger set of
opinions on this specific question (search for "QUESTION" in the
text).
Are there things that are missing?
Here's the draft:
Title: Recommended layout for Git packaging repositories
DEP: 14
State: DRAFT
Date: 2014-11-04
Drivers: Raphael Hertzog <hertzog@debian.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
Introduction
============
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.).
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.
The colon (`:`) needs to be replaced with a percent (`%`), and the tilde
(`~`) needs to be replaced with an underscore (`_`).
Packaging branches and tags
===========================
Packaging branches should be named according to the codename of the
target distribution. In the case of Debian, that means for example
`debian/sid`, `debian/jessie`, `debian/experimental`,
`debian/wheezy`, `debian/wheezy-backports`, etc. We specifically avoid
"suite" names because those tend to evolve over time ("stable" becomes
"oldstable" and so on).
The Git repository listed in debian/control's `Vcs-Git` field should
usually have its HEAD point to the branch corresponding to the
distribution where new upstream versions are usually sent. For Debian,
it will usually be `debian/sid` (or sometimes `debian/experimental`).
QUESTION: some people have argued to use debian/master as the latest
packaging targets sometimes sid and sometimes experimental. Should we
standardize on this? Or should we explicitly allow this as an alternative?
The helper tools that do create those repositories should use a command
like `git symbolic-ref HEAD refs/heads/debian/sid` to update HEAD
to point to the desired branch.
When releasing a Debian package, the packager should create and push
a 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 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>`, `<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 of non-native packages,
that is when 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, 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 can opt to
package it in a non-native way.
Patch queue tags
================
A patch queue branch is a (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 Git repository
-----------------------------------
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.
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.
Changes
=======
* 2014-11-05: Initial draft by Raphaël Hertzog.
--
Raphaël Hertzog ◈ Debian Developer
Support Debian LTS: http://www.freexian.com/services/debian-lts.html
Learn to master Debian: http://debian-handbook.info/get/
Reply to: