Debian Go Packaging

All Go packages are team-maintained in the pkg-go team. This has multiple advantages:

A package maintained within the team should have the name of the team either in the Maintainer field or in the Uploaders field. We use tracker.debian.org’s team functionality and spell the team like this: Debian Go Packaging Team <team+pkg-go@tracker.debian.org>. This enables the team to have an overview of its packages on the DDPO website and ensures that all packages maintained by the team are automatically added to the Debian Package Tracker team.

Putting the team in Maintainers is a strong statement that fully collaborative maintenance is preferred. Anyone can commit to the git repository and upload as needed. A courtesy email to Uploaders can be nice but not required.

If for some reason, a package needs tighter control by its original maintainers, putting the team in Uploaders is a weak statement of collaboration. Help in maintaining the package is appreciated, commits to the git repository are freely welcomed, but before uploading, please contact the Maintainer for the green light.

All Go packages are maintained in git and must be buildable gbp build-package using git-buildpackage.

We use Salsa to store the git repositories.

When using git-buildpackage’s vcsgit feature (e.g. gbp clone vcsgit:golang-text), the following configuration results in git automatically rewriting URLs to be authenticated:

Instead of copying the debian/ directory from some random other package, please use dh-make-golang when you start packaging a new Go library/program.

Also dh-make-golang can create Salsa projects, and configure the CI automatically. Guest accounts on Salsa can’t create projects in go-team group, they can only do it with this approach. Please run dh-make-golang create-salsa-project to see the usage.

Many Go libraries (and also some actual Go programs) don’t have version numbers in the traditional sense, but live in a version control repository of some kind.

In case your upstream does not use version numbers, the Debian package version will look like this:

0.0~git20130606.b00ec39-1

In case you make more than one snapshot per day, you can append a snapshot number after the date, e.g. 0.0~git20130606.2.b00ec39-1. This should rarely be necessary.

During the time when you still work on a package, i.e. before it is ready to upload, please put UNRELEASED into the distribution field in debian/changelog (dch -v <debian_version> will do it automatically). When the package is ready for uploading, change it to unstable (dch -r).

If you change something that has to be noted in debian/changelog, just add a line to the current entry (dch -a). The [firstname lastname] markers added by dch are okay to give credit to non-upload-permitted contributors (also for the initial changelog entry).

Important NOTES to other group members may be placed at the top of the current changelog entry of packages that are not yet ready for upload (e.g. why a package is still UNRELEASED, etc.).

The source package should be named like the upstream project, i.e. docker, you do NOT need to call it golang-docker.

Similarly, the resulting binary package(s) should NOT contain the golang- prefix.

Install dh-golang from Debian unstable so that you are using the newest version. The buildds are using the unstable version, too, so this is important.

dh-golang comes with an example debian/rules file: https://salsa.debian.org/go-team/packages/dh-golang/-/blob/debian/sid/example/rules

You will need to change the value of XS-Go-Import-Path in debian/control to correspond to your program’s upstream package name. This is usually what you would go get when installing it manually. dh-golang needs that information so that it can run go install.

dh-golang sets up a build environment that contains all the libraries that are available in /usr/share/gocode/src, so you need to add Build-Depends to your package. As an example, Debian Code Search depends on golang-github-lib-pq-dev and others: https://github.com/Debian/dcs/blob/master/debian/control#L5

We derive Debian package names from the import path by replacing all slashes with dashes and using a canonical identifier instead of the hostname.

E.g., for github.com/stapelberg/godebiancontrol (which contains "go" already), the resulting Debian package name is golang-github-stapelberg-godebiancontrol-dev.

We use the -dev suffix to keep the namespace clean for shipping shared libraries in the future, which would then be shipped as golang-github-stapelberg-godebiancontrol.

In general, you should use the import path for deriving a name, not the actual package name. Ideally, those are the same anyway.

Here are a couple examples:

All files should be installed into /usr/share/gocode/src/, which corresponds to $GOPATH/src. As an example, for github.com/lib/pq (golang-github-lib-pq-dev), one of the files is /usr/share/gocode/src/github.com/lib/pq/buf.go.

See https://packages.debian.org/sid/all/golang-github-lib-pq-dev/filelist for a full example file list.

Your library package, e.g. golang-github-lib-pq-dev, needs to have all the other Go libraries it depends on in its Depends line. The dependencies need to be available at build time to run the tests (if any) and at installation time so that other packages can be built.

Occasionally, upstream packages might move from one code hosting provider to a different one, as was the case with code.google.com being discontinued and many projects moving to GitHub.

Such a move should be mentioned in debian/changelog and a compatibility symbolic link should be installed using debian/links (see https://salsa.debian.org/go-team/packages/golang-go.crypto/commit/4e0a285a0989331edb5ff580797ab3574197534d for an example). Since the location of the package is also contained in the Debian package’s name, it should be renamed (see https://salsa.debian.org/go-team/packages/golang-go.net/commit/189085288e608ca2720b32d551227d330a561123 for an example).