From Apertis
Jump to: navigation, search

This document aims to explain how to release packages to Apertis projects.


Development workflow

Apertis currently deals with four types of packages:

  • Upstream packages unchanged from Ubuntu
    • The canonical source for this kind of packages is in OBS, unchanged from upstream Ubuntu
  • Upstream packages with minor deviations from Ubuntu
    • The canonical source for this kind of packages is in OBS, with custom DEP-3 patches applied on top of the sources from Ubuntu
  • Upstream packages being actively worked on
  • Apertis-specific packages

Non-native git-based packaging conventions

These conventions are used for packages for which Apertis is not upstream:

  • git repository under the packaging/ folder
  • DEP-14 git layout proposal specification with the following conventions:
    • upstream/{latest,$version} branches with the upstream project code (eg. upstream/2.48.x)
    • apertis/{master,$distro} branches where the upstream branches above get merged with the Apertis packaging (for instance, apertis/17.06)
    • apertis/$version tags (eg. apertis/2.48.0-1ubuntu4co1)
  • OBS contains a MAINTAINED_IN_GIT.txt hint file in the package folder
  • git-buildpackage is used to manage patches, in particular gbp-pq

Non-native process

  • Clone the package Git repository
  • Checkout the apertis/master branch, or the version specific one if you're targeting older releases
  • Import distribution specific patches (debian/patches/) with gbp pq import into a transient branch
  • Hack on the code, adding and amending commits that will be turned into patches using the standard git tools
  • Export the patchset with gbp pq export
  • Add new patches to Git
  • Build the package, build-snapshot should help in this regard
  • Test the package
  • Push changes to Apertis Git following the Contribution process
  • Release changes with the Release process

Native git-based packaging workflow

These conventions are used for packages for which Apertis can be considered upstream:

  • git repository in the main folder
  • packaging metadata are not maintained in separate branches
  • master branch contains the sources for the current development release
  • $version branches (for instance, 17.03) contains the sources for past releases
  • OBS contains a MAINTAINED_IN_GIT.txt hint file in the package folder

Native process

  • Clone the package Git repository
  • Checkout the master branch, or the version specific one if you're targeting older releases
  • Hack on the code, adding and amending commits using the standard git tools
  • Build the package, build-snapshot should help in this regard
  • Test the package
  • Push changes to Apertis Git following the Contribution process
  • Release changes with the Release process

Writing commit messages suitable for generating debian/changelog with gbp-dch

Commit messages should follow the recommended style.

In addition, gbp-dch is a tool to take those commit messages and automatically turn them in entries for debian/changelog.

With it you can use the following tags in your commit messages:

  • Gbp-Dch: {Full,Short}
    • Short will create a short changelog entry using the short commit message (ie. the first line of the commit message)
    • Full will include the long description in the generated changelog entry
  • Apertis: {$TASK_URL,$TASK_ID}, is translated to (Apertis: Txxxx) in debian/changelog for automated task status tracking
  • Thanks: $SOMEONE if you want to give kudos to someone

Running gbp dch will turn a commit message like:

Update website link to demo images

The website has new path for demo images.

Gbp-Dch: Full
Thanks: Mariano for pointing out the issue

Signed-off-by: Héctor Orón Martínez <>

to the following debian/changelog entry:

  * Update website link to demo images.
    The website has new path for demo images.
    Signed-off-by: Héctor Orón Martínez <>
    Thanks to Mariano for pointing out the issue (Apertis: T12345)

Just make sure your package has the following entries in debian/gbp.conf:

ignore-branch = True
meta-closes = Apertis
meta-closes-bugnum = (?:\T?\d+)

Getting prepared for release

Preparing a GPG key

While releasing, the maintainer should provide a GPG-signed version tag. If you have a GPG key already, please skip this section. Otherwise, you need to generate a new key by the following steps.

$ gpg --gen-key

At the prompt, you need to specify several options by interactive mode. In most cases, it provides the default values, but you can use the desired values for each question. After generating a key pair, you can use the command to list GPG keys.

$ gpg --list-secret-keys --keyid-format LONG
sec   2048R/85AC7EE513BFB53B 2017-03-03
uid                          Justin Kim <>
ssb   2048R/ADA53627F4F0C55C 2017-03-03

From the list, the GPG key ID is 85AC7EE513BFB53B. Now you need to let git know the key ID.

$ git config --global user.signingkey "85AC7EE513BFB53B"


Module versioning differs for libraries and applications: libraries need a libtool version specified in addition to their package version. Applications just have a package version.

Libtool versioning

Libraries have two version numbers: a libtool version which tracks ABI backwards compatibility, and a package version which tracks feature changes. These are normally incremented in synchronisation, but should be kept separate because ABI backwards compatibility is not necessarily related to feature changes or bug fixes. Furthermore, the two version numbers have different semantics, and cannot be automatically generated from each other.

A good overview of libtool versioning, and the differences from package versioning, is given in the Autotools Mythbuster.

To update the libtool version, follow the algorithm given in the comments below. This is a typical snippet for setting up libtool versioning:

# Before making a release, the LT_VERSION string should be modified. The
# string is of the form c:r:a. Follow these instructions sequentially:
#   1. If the library source code has changed at all since the last update, then
#      increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
#   2. If any interfaces have been added, removed, or changed since the last
#      update, increment current, and set revision to 0.
#   3. If any interfaces have been added since the last public release, then
#      increment age.
#   4. If any interfaces have been removed or changed since the last public
#      release, then set age to 0.

The following snippet can be used in a to pass that version info to libtool:

my_library_la_LDFLAGS = -version-info $(LT_VERSION)

If a package contains more than one library, it should usually have a separate libtool version for each one.

The standard process for making a release of a module increments the libtool version (if the module is a library) and the package version immediately before release. This is called pre-release incrementing.

The use of pre-release increment for libtool versions means that they are only incremented once for all ABI changes in a release. Some projects use post-release increment for package versions to ensure that the package version number is not outdated (i.e. still equal to the previous release) during the development cycle; we achieve this by altering the version number automatically in the build-snapshot script instead.

Package versioning

The package version number for a library is that passed to AC_INIT(), and the one which is typically known as the project’s version number. For example, the Debian package for a library will use the library’s package version.

Versions of packages developed for Apertis have the form x.y.z and are updated according to the following rules:

  • x starts at 0, and increments when there is a major compatibility break. Libraries with different major versions should usually be parallel-installable.
  • y is the Apertis branch year and month as a single 4-digit number, for instance 1706.
  • z is 0 for the first release to each branch, and goes up for each release (whether it is a feature release or bugfix-only).

Release process

The packages maintained in the Apertis git repositories should be released with the following procedure, roughly based on the GNOME release process.

  1. Make sure all the git-buildpackage local branches (apertis/*, upstream/* and pristine-tar) are available and up-to-date:
    $ gbp pull
  2. Choose the new version number by the rules of #Libtool versioning and #Package versioning
  3. Make sure you have no local changes and you are in right branch (See Git-based packaging workflow)
    $ git status
  4. bump for a new upstream release, unless the module uses git-version-gen in which case you don't need to do anything.
  5. debian/changelog: auto-generate the changelog entry and mark it for release replacing UNRELEASED with the current version (for instance 16.12)
    $ gbp dch --auto -R
  6. Make sure that all tasks this release is fixing are mentioned in debian/changelog in the form (Apertis: T1234)
  7. For a library: check that any Since: UNRELEASED annotations have been replaced with Since: 0.1612.1 or whatever, for example using git grep UNRELEASED
  8. For a library: bump the Libtool current/revision/age versions in
  9. Build test the package with build-snapshot
    $ build-snapshot user@apertis-vm # replace this with a SSH-accessible Apertis SDK installation
  10. For a library: look for output from dpkg-makeshlibs reporting new symbols that should be in the .symbols files. Add them to the .symbols files, with the upstream version (for example mylib_foo@Base 0.1612.0, not mylib_foo@Base 0.1612.0-0co1).
  11. Now you need the following variables for the next steps.
    PACKAGE=$(dpkg-parsechangelog -SSource)
    DEBVERSION=$(dpkg-parsechangelog -SVersion)
    RELEASE=$(dpkg-parsechangelog -SDistribution)
    COMPONENT=$(cat debian/source/apertis-component)

    If build-snapshot succeeds, commit the changes.

    $ git commit --all --signoff -m "Release $PACKAGE version $VERSION"
  12. Submit a merge request for review following the contribution process guidelines, paying special attention to the section about release commits if you are releasing a new version of the package.
  13. If this is a native package and you're also doing an upstream release, tag it (note the versioning must have a v, for instance v1.2.3). Skip this for non-native packages.
    $ git tag v$VERSION -s -m "Release $PACKAGE $VERSION"
  14. Tag the Apertis release.
    $ gbp buildpackage --git-tag --git-tag-only
  15. Run build-snapshot again. This is because the build procedure is slightly different with the tags.
  16. Push the tags and push the changes (in that order so CI never builds these commits without the tags being present)
    $ git push origin v$VERSION apertis/$DEBVERSION
    $ git push
  17. If you happened to push the commits before the tags, you will need to manually trigger the corresponding CI job on Jenkins (or ask someone to do it for you)
  18. Wait for an OBS maintainer to accept the request to merge the package built in the corresponding apertis:$RELEASE:snapshots project.

Work done

Once accepted by OBS maintainer, you can update the package by apt-get after a daily Apertis image is released.

External links

Personal tools