Packaging in Apertis is handled through a set of git repositories hosted on GitLab containing the sources for every packages. GitLab CI pipelines take care of propagating updates to OBS to build and publish the resulting binaries.

Repository contents

The packaging git repositories follow the DEP-14 Git layout specification with the following conventions:

DEP-14 in Apertis

  • upstream/${UPSTREAM_DISTRIBUTION} branches with the unpacked upstream project code from the debian package (e.g. upstream/buster)
  • debian/${UPSTREAM_DISTRIBUTION} branches with the Debian changes on top of the upstream project code (e.g. debian/buster)
  • debian/${UPSTREAM_VERSION} tags (e.g. debian/2.48.0-1)
  • apertis/${APERTIS_RELEASE} branches where the debian branches above get merged with the Apertis packaging (e.g. apertis/v2019pre)
  • apertis/${APERTIS_VERSION} tags (e.g. apertis/2.48.0-1co1)
  • pristine-lfs branch containing the information to fetch the original tarballs stored on Git-LFS via pristine-lfs

Development environment

All the instructions below assume an Apertis development enviroment: either boot the Apertis SDK or enter the apertis-*-package-source-builder Docker container:

docker pull${APERTIS_RELEASE}-package-source-builder
docker run -it --rm --env HOME -w "$(pwd)" -v "$HOME:$HOME" -v "$HOME:/root" --security-opt label=disable${APERTIS_RELEASE}-package-source-builder bash

How to manually sync an Apertis package with a new version

Upstream updates are usually handled automatically by the ci-package-builder.yml Continous Integration pipeline, which fetches upstream packages, merges them with the Apertis contents and directly creates Merge Requests to be reviewed by maintainers.

However, in some cases it is necessary to manually pull upstream contents:

  1. the CI failed to merge the upstream update with the downstream changes, so a developer must reproduce the merge and fix the conflicts
  2. for some reason it in necessary to manually pull updates from a new upstream distribution/suite

The steps below can guide you on manually pulling upstream updates:

This guide assumes the developer is a member of the Apertis development team, contributors who are not a member of this team will need to fork the package to their private workspace (as documented in the development process before manually updating the package and submit a merge request from there.

  1. On GitLab, fork the project to your personal namespace.

  2. Check out the source repository

    git clone${GITLAB_USER}/${PACKAGE}
    cd ${PACKAGE}
  3. Only if moving to a new upstream distribution, prepare the upstream base branches using the current upstream branches as a base:

    git push origin origin/upstream/${UPSTREAM_BASE}:refs/heads/upstream/${UPSTREAM_DISTRIBUTION}
    git push origin origin/debian/${UPSTREAM_BASE}:refs/heads/debian/${UPSTREAM_DISTRIBUTION}
  4. Sync the upstream contents

    apertis-pkg-pull-updates --package=$PACKAGE --upstream=$UPSTREAM_DISTRIBUTION --mirror=$MIRROR
    git push origin --follow-tags pristine-lfs upstream/${UPSTREAM_DISTRIBUTION} debian/${UPSTREAM_DISTRIBUTION}
  5. Merge the upstream changes

    git checkout -b ${PROPOSED_BRANCH} ${TARGET_BRANCH}
    apertis-pkg-merge-updates --upstream=debian/${UPSTREAM_DISTRIBUTION} --downstream=${PROPOSED_BRANCH}
  6. Only if the merge fails, fix the conflicts and continue

    git status
    # fix conflicts
    git merge --continue
    dch --local co --no-auto-nmu
  7. Check debian/changelog and update it if needed by listing all the remaining Apertis changes

    $EDITOR debian/changelog
    git commit --signoff --amend debian/changelog
  8. Push your changes for review

    git push origin --follow-tags pristine-lfs upstream/${UPSTREAM_DISTRIBUTION} debian/${UPSTREAM_DISTRIBUTION}
    git push -o merge_request.create

How to work with downstream packaging changes

The packaging repositories follow the Apertis contribution process.

However, the deb packaging format does not allow changes outside of the debian/ folder: changes to the upstream files should be carried as patches, shipped in debian/patches folder.

To make working with those patches a bit easier for those used to git rebase, the gbp pq tool provides a way to convert patches to git branches and back.

How to issue a release

The process for landing downstream changes is documented in the ci-package-builder documentation.

How to add a new packaging repository

The process for adding new packages from Debian is documented in the ci-package-builder documentation.