After reading this document, you should be able to produce Debian packages for Go software.
All Go packages are team-maintained in the pkg-go team. This has multiple advantages:
There are no single points of failure, if one maintainer cannot continue maintaining a package, another maintainer can easily help out or take over.
All packages can share the same technical standards and workflows.
When working within a team anyway, it is much easier to get help on any technical issue.
A package maintained within the team should have the name of the team either in
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 <firstname.lastname@example.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
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
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.
Packaging in git
All Go packages are maintained in git and must be buildable using git-buildpackage.
We use Salsa to store the git repositories.
Git setup for automatically authenticating
When using git-buildpackage’s vcsgit feature (e.g.
vcsgit:golang-text), the following configuration results in git automatically
rewriting URLs to be authenticated:
git config --global url."git.debian.org:/git/".insteadOf "https://anonscm.debian.org/git/" git config --global url."email@example.com:".insteadOf "https://salsa.debian.org/"
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.
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:
The 0.0 in the beginning is used to allow upstream to adopt version numbers at any point in time and also to make it clear that no traditional version number is used for this package.
The second part is the version control system, e.g. git, hg, svn.
Afterwards, a date follows in the format YYYYMMDD.
After the dot, the version control system revision follows, to make it clear which commit was packaged, as many repositories have multiple commits on a given day.
The last part after the dash is the Debian version number.
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
dch -v <debian_version> will do it automatically). When
the package is ready for uploading, change it to
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
A binary-only package is a package that contains a program written in Go, but
no source code. An example is
docker, which is written in Go, but does not
offer an API (thus no source code).
The source package should be named like the upstream project, i.e.
you do NOT need to call it
Similarly, the resulting binary package(s) should NOT contain the
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
You will need to change the value of
to correspond to your program’s upstream package name. This is usually what you
go get when installing it manually.
dh-golang needs that information
so that it can run
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:
Library (or binary + library) packages
Libraries written in Go are packaged for Debian with the only purpose of
building other Go programs for Debian. They are specifically not available
for users in their regular development workflow. For that, users should use
get. The rationale behind this decision is:
go getyou are forced to set up the environment variable
$GOPATHwhich you need for other
go test, etc.).
Debian packages install files to system locations, which users cannot modify. That means that users would not be able to upgrade packages with the canonical
go get -u <package>. Even worse, when using sudo to forcibly modify the system files, it still would not work since no VCS information is contained in the Debian packages.
We derive Debian package names from the import path by replacing all slashes with dashes and using a canonical identifier instead of the hostname.
github.com/stapelberg/godebiancontrol (which contains "go"
already), the resulting Debian package name is
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:
|Import path||Debian package name|
All files should be installed into
/usr/share/gocode/src/, which corresponds
$GOPATH/src. As an example, for
(golang-github-lib-pq-dev), one of the files is
See http://packages.debian.org/sid/all/golang-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.
Upstream package moves
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
for an example). Since the location of the package is also contained in the
Debian package’s name, it should be renamed (see
for an example).