This document lists the proposed but unimplemented changes to the pkg-go workflow which the pkg-go team came to a consensus and which Michael Stapelberg summarized in November 2017 to facilitate further discussions and eventual implementation.

The story began with this email: [pkg-go] Minutes for the DebConf17 BoF: https://alioth-lists.debian.net/pipermail/pkg-go-maintainers/Week-of-Mon-20170807/014361.html

This proposal for workflow changes is still a work-in-progress.

dh-make-golang has not yet adapted to this new proposed workflow. For newcomers and the less experienced, myself included, it is recommended to stick with the old workflow until all the infrastructures supporting the migration to the new workflow are in place. — AF

1. Proposed changes as of 2017-11

1.1. “upstream” branch should contain upstream git history

TODO: describe the best strategy to migrate a package

1.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

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.

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

1.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?

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

1.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/stretch.

Migration

  1. TODO: describe the branch rename.

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

1.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.