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. Even if the package has already its own repository for the normal maintenance work, we create our own one in order to keep the (E)LTS-specific upload to avoid any conflicts with the original maintainer(s).

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.

Prepare a new repository

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/buster 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/buster, debian/jessie, etc.

We drop the main branch and create corresponding branches.

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

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

  3. Go to “Settings->Repository->Default Branch” and choose debian/buster->”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/.gitlab-ci.yml

    2. Enter in ‘Timeout” 6h.

    3. Press “Save changes”.

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 commit -am'Remove README.md'

  2. Create upstream branch and import the source:

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

  3. Import initial debian-folder:

    git checkout debian/buster
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/buster

Add gitlab-ci.yml

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

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

variables:
    RELEASE: 'buster'
    SALSA_CI_COMPONENTS: 'main contrib non-free'
    SALSA_CI_DISABLE_REPROTEST: 1
    SALSA_CI_DISABLE_LINTIAN: 1

    Alternatively file can be downloaded:

    wget https://salsa.debian.org/lts-team/packages/miscellaneous/-/raw/main/stretch/.gitlab-ci.yml -P debian
sed -i -e 's@stretch@buster@g' debian/.gitlab-ci.yml

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

  2. Commit and push the file:

    git add debian/.gitlab-ci.yml
git commit -am'Add debian/.gitlab-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 .gitlab-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/buster

  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/buster
git push --tags