Using git for team packages

This page is UNOFFICIAL

As of this writing (2014-08-22), the Debian/Python team still officially uses Subversion to manage all team packages. The contents of this page are PROPOSED as a team policy and recommendations for using git to manage team package. It is still under active discussion on the debian-python mailing list. Please provide your feedback there.

There are many advantages to team-based package development. The DPMT and PAPT have very excellent, knowledgeable, and experienced Python and Debian developers and our goal is to bring the very best Python experience to Debian users and developers. We're here to help each other and provide consensus (if not 100% agreement) on best practices. Collaboration has many benefits, and one of the things that aids effective collaboration is common tools and workflows surrounding packaging, while still providing individual maintainers the freedom to adapt those practices to their preferences, and the peculiarities of the packages.

One of the perks of being in a team is that all of our packages are managed in a similar way, using similar tools and workflows. This is great because any team member can immediately get the source of a package to do an update or a bug fix, and they don't have to first try to figure out how the package is version controlled. Plus, we can have nice wiki documentation which help new team members how to do things, and almost anyone on IRC can immediately give you advice. We use a common set of vcs procedures to ensure consistency among all of our packages. Both the DPMT and PAPT teams use the same version control system, layout, and workflows.

It is a team requirement that all packages be managed using the same version control system. As of this writing, that vcs is Subversion (svn).

We recognize however, that modern vcses, especially of the distributed variety, provide a lot of additional benefit for packagers. Such vcses include git, Mercurial (hg), and Bazaar (bzr), among others. git seems to be the most popular, so we are investigating it as a possible replacement for svn for team managed projects.

git workflows

There are two predominant git-based workflows in use within Debian for package management, git-dpm and git-buildpackage. While there is some overlap and similarities, there are some subtle differences both technically and in ease-of-use that makes it useful for the team to mandate one or the other regimes. You can gain some background on their applicability to team packages by reading these threads in the mailing list: git-dpm and git-buildpackage. dgit is an interesting possibility, since its repositories reflect the exact representation of the package in the Debian archives.

After experimentation and discussion, the Debian Python Team requires the use of git-dpm for managing team packages.

Again, this is a provisional decision.

The rest of this page is written as if the decision has been made to go with git-dpm. Should the team decide otherwise, this page will be rewritten! It's a useful point of discussion however, to set a stake in the ground.

git-dpm imposes some restrictions on branch names, but you still have some leeway. However, as a team we are strongly recommending you use the default branch names, specifically:

If you use other branch names allowed by git-dpm, please have a good reason (not just personal preference, remember - take one for the team!), and you must document the differences in debian/README.source. The default branch names will help the repo interoperate better with other tools.

Where do the team's git branches live?

Alioth, under the python-modules directory. To set up a new repository here, you should follow these instructions. They require ssh access to Alioth, but if you have push permissions, you should have ssh permissions. Ask a team member for help if you are unable to do this. These instructions set up the hooks for commit notifications and such:

$ ssh git.debian.org
$ cd /git/python-modules
$ ./setup-repository <srcpkgname> "<srcpkgname> packaging"
$ exit

Of course, use your own source package name for <srcpkgname>.

We will still require all team packages to be available on git.debian.org. Please do not host your team maintained packaging branches anywhere else; e.g. github is not appropriate for the packaging branches, although it is TBD whether mirrors and pull requests on github will be honored.

Use these Vcs-* headers in your debian/control file:

Vcs-Git: git://anonscm.debian.org/python-modules/packages/<srcpkgname>.git
Vcs-Browser: http://anonscm.debian.org/gitweb/?p=python-modules/packages/<srcpkgname>.git

Transition plan

It seems unfeasible to mass-migrate all of the teams packages from svn to git in one fell swoop. The plan is then to migrate packages opportunistically, with a hard deadline sometime way in the future (1 or 2 years?) after which all remaining packages will be migrated. The rough steps to migrate the team would then be:

Use cases

Here are some common scenarios and use cases. There may be other ways to accomplish these tasks so if you find a more efficient way of doing something, please update these pages and discuss with the team via the debian-python mailing list. Feel free to add more use cases here too! Your experience is valuable.

Creating a new package

First, Initialize the package directory on git to set up the bare repo (with hooks installed) that you will push your branch.

Next, you can either ?import an existing .dsc file or start from scratch. Here's are the steps from the manpage that seem to work well:

You'll now be left on the master branch, i.e. the packaging branch. You'll also have upstream (raw tarball contents) and pristine-tar branch.

Fill in the rest of your debian/ directory, then do this:

You can now build your package using whatever tools you like, including debuild, dpkg-buildpackage, and even git-buildpackage!

Push your repo to git.debian.org:

At this point, I like to cd to a different directory and do a git clone ssh://git.debian.org/git/python-modules/packages/<srcpkgname>.git and then continue working from the <srcpkgname> directory. To prove that all the branches got pushed correctly, in this fresh clone, checkout the master, pristine-tar, and upstream branches.

Building and tagging

Patching

New upstream release

Sponsoring, mentoring, reviewing

- pull requests

More information and resources