Git workflow for the (E)LTS packages

Rationale

(E)LTS team manages several releases and many packages. To keep the history of all uploads the git-workflow is mandatory. All packages are hosted in this project on salsa.debian.org.

For each package we have a dedicated repository. Our preference is to do the work in the maintainer repository (assuming that the maintainer has a DEP-14 layout and is willing to have LTS/ELTS work in the same repository). If that is not possible, then our next preference is to fork the project in Salsa, under the aforementioned lts-team/packages group. Only if neither working in the maintainer repo nor forking an existing Salsa repo is possible, do we want to proceed with creating an entirely new project under lts-team/packages. Regardless of whether the work is done in the maintainer repo or in a repo under lts-team/packages (or both in the case of LTS in the maintainer repo and ELTS in a fork or separate repo), the repo location(s) must be listed in the package DB (as in one must add it manually during LTS/ELTS work).

Note that the package DB (packages.yml) and the package-operations script described below are in a repository which is only available to paid LTS contributors. If you do not have access to this repository but need to perform some of these actions, please mail the LTS mailing list and request assistance.

Each package must have a working CI (continuous integration) pipeline. An exception can be granted to some large or difficult packages where the CI is difficult to setup or is impossible for some technical reason. Each exception should be discussed on the LTS mailing list.

This document describes the steps needed for the new repository creation, setting up a CI system and preparation of an upload.

The following steps for the repo creation were automated in the package-operations script from gitlab.com:freexian-lts/debian-lts. The repository can be created during the package addition to the dla-needed.txt or with the command bin/package-operation --creategitrepo --package $packagename. Be sure to have a created token as described here.

Fork an existing repository

If working in the maintainer repo is not possible, then the next thing to try is forking the repo. This assumes that the maintainer repo already exists in Salsa somewhere. Repositories should be forked under the lts-team/packages group. If you lack sufficient permissions for this, contact the LTS mailing list for help.

Prepare a new repository

Attention

A new repository should only be created if neither working in the maintainer repo nor forking the existing Salsa repo are possible.

Note

Please check whether an original package is using git-workflow/Salsa-CI already. If so, it is preferred to fork the maintainer’s existing repo to reduce resource consumption on Salsa.

As an example, the package admesh for the LTS upload into debian/bullseye will be used. You will of course have to use your own package name and corresponding release.

  1. First check whether the repository for this package exists. If yes; skip these steps and go to the Prepare an upload… section.

  2. Go to the main repo and press “New project” -> “Create blank project”.

  3. For the “Project name” field, enter admesh.

  4. Press “Create project”.

We are using the DEP-14 schema, where the branches are named according to the releases, such as debian/bullseye, debian/buster, etc.

We drop the main branch and create corresponding branches.

  1. Go to “Code->branches” and press “New branch”.

  2. Branch name -> debian/bullseye or any other suite, which is needed for your work now.

  3. Go to “Settings->Repository->Default Branch” and choose debian/bullseye->”Save changes”.

  4. Go to “Repository->Branches” and remove main branch.

Setting up a CI

  1. Go to “Settings->CI/CD”. Expand “General pipelines”:

    1. Enter in “CI/CD configuration file”: debian/salsa-ci.yml

    2. Enter in “Timeout”: 6h (note: this is capped by the Runner’s timeout, current 3h, and SALSA_CI_BUILD_TIMEOUT_ARGS, currently 2.75h)

    3. Press “Save changes”.

  2. Expand “Runners”. Ensure there’s an ARM runner enabled: LTS Team ARM runner and/or salsaci-arm64-runner*.

Import of new version of the package

Assume, you have a folder “orig” where the current version of the package is download and uncompressed.

ls -l ../orig/

drwxr-xr-x    - anton 16 May 22:36 admesh-0.98.2
.rw-r--r-- 5.6k anton 16 May 22:36 admesh_0.98.2-3.debian.tar.xz
.rw-r--r-- 2.1k anton 16 May 22:36 admesh_0.98.2-3.dsc
.rw-r--r--  34k anton 16 May 22:36 admesh_0.98.2.orig.tar.xz

  1. In the terminal locally clone firstly an empty Repository.

    git clone git@salsa.debian.org:lts-team/packages/admesh.git
cd admesh
rm README.md
git rm README.md
git commit -am'Remove README.md'

  2. Create upstream branch and import the source:

    git checkout -b upstream
gbp import-orig --debian-branch=debian/bullseye --pristine-tar  ../orig/admesh_0.98.2.orig.tar.xz

  3. Import initial debian-folder:

    git checkout debian/bullseye
cp -r ../orig/admesh-0.98.2/debian .
git add debian
git commit -am'Initial import of debian/ folder'

  4. Delete debian/gbp.conf if it exists. We do this in a separate commit to record it in Git history.

    rm debian/gbp.conf && git commit -am 'Remove debian/gbp.conf'

  5. Tag the initial upload:

    gbp buildpackage --git-tag-only --git-sign-tags --git-debian-branch=debian/bullseye

Add salsa-ci.yml

  1. Create the file debian/salsa-ci.yml with the following content:

    ---
# LTS/ELTS CI

include:
- https://salsa.debian.org/lts-team/pipeline/raw/master/recipes/bullseye.yml

# These didn't work before LTS, not attempting to fix after freeze
#blhc:
#  allow_failure: true

    The full documentation for the Debian pipeline may be found on the lts-team/pipeline repository.

  2. Commit and push the file:

    git add debian/salsa-ci.yml
git commit -am'Add debian/salsa-ci.yml'
git push --all
git push --tags

If all went well, you can go to the salsa on the package page, section “CI/CD->Pipelines” and check whether the package is being built successfully or not.

A test image

As you see in our salsa-ci.yml file, we disable lintian and reprotest jobs because they are less relevant for the minimal security updates. Those options can be switched on explicitly. Lintian is also disabled due to the fact that the newer version is used for older releases and it sometimes produces some errors.

Prepare an upload of the already existing package

  1. Clone an existing repository:

    git clone git@salsa.debian.org:lts-team/packages/admesh.git

  2. Hack on the package

  3. Try to build locally:

    gbp buildpackage --git-debian-branch=debian/bullseye

  4. After git push you can check the status of the package

  5. If the build was successful, the package should be tagged:

    gbp buildpackage --git-tag-only --git-sign-tags --git-debian-branch=debian/bullseye
git push --tags