1. 2025-01 changes (proposed)

For the related discussion thread, see:

1.1. Adopt modern (year 2020) version of DEP-14 branch naming

The Go team was an early adopter of DEP-14. When DEP-14 matured, the recommended Debian packaging branch became debian/latest, and the upstream import branch became upstream/latest. The Go team should align with the latest DEP-14 recommendations.

Every Go package that adopts DEP-14 should include a debian/gbp.conf file to eliminate the need for maintainers to manually pass branch names to git-buildpackage:

  [DEFAULT]
  # DEP-14 branch names
  debian-branch = debian/latest
  upstream-branch = upstream/latest

Note that the above is not a complete debian/gbp.conf file, just the bare minimum.

New Go packages will include the above as part of the fully featured team gbp.conf template automatically when using the latest version of dh-make-golang.

Existing packages can transition using dep-14-convert available in the next devscripts release. Example commands produced by it below:

  git branch -m debian/sid debian/latest
  salsa rename_branch go-team/packages/golang-github-adrg-xd --source-branch=debian/sid --dest-branch=debian/latest
  salsa update_projects go-team/packages/golang-github-adrg-xd --rename-head --source-branch=debian/sid --dest-branch=debian/latest
  git branch -m debian/sid upstream/latest
  salsa rename_branch go-team/packages/golang-github-adrg-xd --source-branch=debian/sid --dest-branch=upstream/latest
  git checkout debian/latest
  sed -i 's/^debian-branch[[:space:]]*=.*/debian-branch = debian\/latest/' debian/gbp.conf
  echo "upstream-branch = upstream/latest" >> debian/gbp.conf
  git commit -a -m "Update git repository layout to follow DEP-14"

Transitioning to new debian/latest and upstream/latest may happen whenever convenient to the maintainer/uploader.

1.2. Clarify the difference between upstream/latest and the actual upstream branch

In DEP-14, the upstream-branch refers to the branch targeted for upstream imports, whether from upstream release git tags, upstream tarball imports, or both. The Go team should adopt the upstream/latest naming convention, replacing the use of the upstream branch name.

The branch name upstream should not be used at all, either as a branch or as a remote name.

The actual upstream branch should retain the name used by upstream, typically main. Upstream remotes should be named upstreamvcs for clarity. This naming convention is applied automatically when a Go team repository is checked out using:

  gbp clone --add-upstreamvcs git@salsa.debian.org:go-team/packages/example.git

This requires the debian/upstream/metadata file to include the upstream Git repository URL.

1.3. Use pristine-tar and verify upstream signatures when available

In the past there was some challenges in how reliably the pristine-tar feature worked. Nowadays Debian maintainers no longer report issues with it, so there shouldn’t be any reason to not use it, as it fulfills its purpose well.

Using the pristine-tar feature allows git-buildpackage to recreate the upstream release tarball, so it is bit-by-bit identical with the original. This in turn allows to verify for upstream signatures, when upstream publishes them.

Additionally, using pristine-tar reduces the likelihood any errors related to management of the original source tarball, such as:

  Subject: gh_2.46.0-3_source.changes REJECTED
  gh_2.46.0-3.dsc: Invalid size hash for gh_2.46.0.orig.tar.gz:
  According to the control file the size hash should be 840361,
  but gh_2.46.0.orig.tar.gz has 839976.

1.4. Auto-format debian/control with -ast

Go team packages should use wrap-and-sort -ast or debputy reformat --style black to format debian/control files. Both tools produce the same format, as shown below:

  Package: glow
  Section: utils
  Architecture: any
  Depends:
   ${misc:Depends},
   ${shlibs:Depends},
  Built-Using: ${misc:Built-Using}
  Description: Render Markdown on the command-line
   Glow is a terminal based Markdown reader designed from the ground up to bring
   out the beauty — and power — of the command-line.

1.5. Apply all of the above by default in dh-make-golang

New packages can follow the updated workflow immediately by using the following command:

  dh-make-golang make -dep14 -git_revision v1.0.8 -type program -upstream_git_history -wrap-and-sort ast github.com/cilium/pwru

Once dh-make-golang is updated with the new defaults, the command will be simplified, requiring only the version, type, and URL:

  dh-make-golang make -git_revision v1.0.8 -type program github.com/cilium/pwru

2. 2017-11 changes (implemented in 2019 and in effect)

For the corresponding discussion thread, please see https://lists.alioth.debian.org/pipermail/pkg-go-maintainers/Week-of-Mon-20171016/015809.html

2.1. “upstream” branch should contain upstream git history

TODO: describe the rationale and workflow, and how to deal with nonfree and vendored files

Migration

  1. Add upstream repository as a new remote. Then fetch its history.

    git remote add up https://github.com/paultag/go-topsort
git fetch up

  2. Delete/Rename the old upstream branch, and checkout a new upstream branch.

    git branch -m upstream old/upstream
git checkout -b upstream up/master

  3. Merge upstream history into the packaging branch, at the same point where the previous upstream was, usually based on release tags if upstream does releases; otherwise, the Debian release number will contain the commit ID.

    git diff <upstream_commit_id> old/upstream  # should be no differences
git checkout master
git merge --allow-unrelated-histories <upstream_commit_id>

Packaging new upstream release

When packaging new upstream release, you can fetch upstream remote and merge it into upstream branch.

If upstream does tag release, you can merge the new tag into upstream branch, and create a new tag with upstream/<version> format, which will be used by gbp.

git fetch up
git checkout upstream
git merge <upstream_tag>
git tag -a upstream/<version>
git checkout master
git merge upstream/<version>

If upstream doesn’t have tags, you can merge the latest commit into upstream branch, and create the upstream/<version> tag by commit date and id.

git fetch up
git checkout upstream
git merge up/master
TAG=$(git log --date=format:%Y%m%d --pretty=upstream/0.0_git%cd.%h -1)
git tag -a "$TAG"
git checkout master
git merge "$TAG"

2.2. Drop pristine-tar branches

Rationale

The appeal of using pristine-tar was that a byte-for-byte equal orig tarball could be easily (and automatically) generated, preventing rejected uploads and aiding future historians with reproducibly rebuilding older versions. Further, using pristine-tar results in a self-contained git repository which makes for a simple mental model (as opposed to the git repository + orig tarball in parent directory model).

In reality, pristine-tar branches weren’t consistently updated across our repositories for a number of reasons, resulting in despised additional maintenance effort for little benefit (uploads may or may not be rejected, depending on the repository state).

Hence, even though the new gbp push command and a consistent setting of pristine-tar=True in debian/gbp.conf might help improve consistency, we decided to abandon pristine-tar altogether.

Old workflow

  • Obtain a byte-for-byte equal orig .tar.gz file: pristine-tar list and pristine-tar checkout

  • Build against a byte-for-byte equal orig .tar.gz file: enable gbp buildpackage’s pristine-tar option, e.g. via --git-pristine-tar or pristine-tar=True in debian/gbp.conf.

New workflow

  • Obtain a byte-for-byte equal orig .tar.gz file: origtargz(1)

  • Build against a byte-for-byte equal orig .tar.gz file: use origtargz before building

Note
 Using --git-upstream-tree=TAG (the default) is not sufficient to obtain a byte-for-byte equal orig .tar.gz file. In stapelberg’s tests, only 5% of pkg-go’s git repositories would match the orig .tar.gz in the archive.
Tip

Configure gbp-clone(1) to automatically run origtargz(1) by adding the following to ~/.gbp.conf:

[clone]
postclone=origtargz

Migration

  1. Remove any pristine-tar-related settings from this repository’s gbp config files, defaulting to pristine-tar=False:

    for f in .gbp.conf debian/gbp.conf .git/gbp.conf
do
    [ -e "$f" ] && sed -i '/^pristine-tar/d' "$f"
done

  2. Delete the pristine-tar branch: git push origin :pristine-tar

TODO: verify step 2 works

2.3. Auto-format debian/control

Rationale

Common formatting increases consistency between packages maintained by pkg-go and auto-formatting frees up time previously spent on manual formatting.

Old workflow

Manually format control files such as debian/control.

New workflow

Use wrap-and-sort(1) from the devscripts package in the root of the Debian package directory:

wrap-and-sort --wrap-always --trailing-comma

The command line arguments result in a format which produces minimal diffs whenever new values are added or old values are removed.

TODO: is there any editor integration for wrap-and-sort yet?

Tip

To auto-format before committing, create the following hook at .git/hooks/pre-commit:

#!/bin/sh
wrap-and-sort --wrap-always --trailing-comma

Migration

  1. Run wrap-and-sort --wrap-always --trailing-comma

2.4. Adopt DEP-14 branch naming

Rationale

Consistency in our branch naming makes it easier for team-internal and team-external contributors to understand/interact with our packaging repositories.

Old workflow

The default branch of a package was named master.

New workflow

See DEP-14 for the full text. In a nutshell:

  • The default branch of a package should be named debian/sid.

  • git HEAD should point to debian/sid.

  • The upstream git history should live in a branch named upstream.

    TODO: wait until discussion in #812721 came to an agreement

  • Packages which release into stable releases should use the codename of the target distribution, e.g. debian/bookworm.

Migration

  1. TODO: describe the branch rename.

  2. git symbolic-ref HEAD refs/heads/debian/sid

2.5. Derive debian/changelog from git history

Rationale

Some pkg-go repositories used the old workflow, some used the new workflow — this was just a personal preference of whoever last touched the repository.

Unifying this difference eases contributions to any pkg-go repository.

Old workflow

  • Document your changes in a pending debian/changelog entry with the special suite name UNRELEASED.

  • Document your changes in your git commit(s).

New workflow

  • Document your changes in your git commit(s).

  • Before uploading the package to Debian, use gbp dch -R --commit.

TODO(stapelberg): install https://paste.debian.net/hidden/c3a81ddf/ (git update hook which declines old-workflow d/changelog updates) in all pkg-go repositories

Migration

TODO: remove pending d/changelog entries from existing packages.