Skip to content
Snippets Groups Projects
Commit 4f0c4711 authored by Martyn Welch's avatar Martyn Welch Committed by Emanuele Aina
Browse files

Shift versioning and dch information out of howtoreleasepackages


The versioning information doesn't sit very well in the releasing
packages guide. Add this to the information on binary package
versioning to make a more holistic page on versioning.

Move the information on dch tags to the version_control guide where
it is mentioned.

The rest of this guide is very out of date. We have a number of other
guides on releasing packages, drop this one.

Signed-off-by: default avatarMartyn Welch <martyn.welch@collabora.com>
parent 1252b0f8
No related branches found
No related tags found
1 merge request!45Reformat and move contents of guidelines
......@@ -84,7 +84,7 @@ API stability guarantees are strongly linked to project versioning; both
package versioning and libtool versioning. Libtool versioning exists entirely
for the purpose of tracking ABI stability, and is explained in detail on the
[Autotools Mythbuster](https://autotools.io/libtool/version.html) or the
[Versioning page]( {{< ref "/guidelines/howtoreleasepackages.md" >}} ).
[Versioning page]( {{< ref "versioning.md#libtool-versioning" >}} ).
Package versioning (*major.minor.micro*) is strongly linked to API stability:
typically, the major version number is incremented when backwards-incompatible
......@@ -92,8 +92,8 @@ changes are made (for example, when functions are renamed, parameters are
changed, or functions are removed). The minor version number is incremented
when forwards-incompatible changes are made (for example, when new public API
is added). The micro version number is incremented when code changes are made
without modifying API. See the [Versioning page]( {{< ref
"/guidelines/howtoreleasepackages.md" >}} ) for more information.
without modifying API. See the
[Versioning page]( {{< ref "versioning.md#package-versioning" >}} ) for more information.
API versioning is just as important for D-Bus APIs and GSettings schemas (if
they are likely to change) as for C APIs. See the [documentation on D-Bus API
......
+++
date = "2019-11-15"
weight = 100
title = "Binary Package Versioning"
aliases = [
"/old-wiki/Build_and_Integration_infrastructure_documentation"
]
+++
# Understanding Build Suffixes
For every release (*Developer, Preview, Product*), we add a build suffix string
to the packages, which relates to the release name of Apertis. The build
suffix gets added to every built .deb package. Having a build suffix helps
determine which Apertis release the .deb package was built for.
The suffix string is constructed of: `b<Release_Name>b<B_CNT>`.
- The initial `b` is for backward compatibility ensuring the new suffix string
can work well together with older release packages.
- `<Release_Name>` refers to the Apertis release's name.
- `b<B_CNT>` refers to being a binary build along with the build count.
For example, for the Apertis Developer Release `v2020dev0` we add the string
`bv2020dev0b<B_CNT>` to the project configuration on OBS. Similarly, for an
Apertis Product Release of `v2019.0` we add the string `bv2019.0b<B_CNT>` to
the project configuration on OBS.
## Point Releases
A point release rolls the packages previously released in the update and
security repositories into the stable branch. It is required to ensure that the
packages in the new point release have a higher version than the binary package
in the updates or security repositories, it is thus necessary to include the point
releases numbering (e.g. `v2019.1`, `v2019.2`) in the build suffix.
For example, during the initial release of the v2019 release, the build suffix
was `bv2019.0b<B_CNT>`. The same build suffix is inherited by the updates and
security sub-repositories during this time period. Before doing a new point
release *v2019.1*, the build suffix of the main repositories
(`apertis:v2019:target`, `apertis:v2019:development`, `apertis:v2019:sdk`,
`apertis:v2019:hmi` etc) is set to `vb2019.1b<B_CNT>`.
Once this step has been taken, changes previously commited to Apertis update
and security branches (such as `apertis/v2020-updates` and
`apertis/v2020-security`) are merged into the main release branch
(`apertis/v2020`), thus triggering a build and generation of a package with the
required point release suffix. This ensures that the packages synced from the
updates and security sub-repositories have higher versions than packages from
the updates and security sub-repositories. Once the merge has been completed,
the equivalent packages in the update and security branches are purged to allow
these branches to be used for following updates and security fixes to the new
point release.
+++
date = "2019-11-15"
weight = 100
title = "Versioning"
aliases = [
"/architecture/binary_package_versioning/",
"/guidelines/versioning/",
"/old-wiki/Guidelines/Versioning",
"/old-wiki/Build_and_Integration_infrastructure_documentation"
]
+++
It is important to properly
[version](https://en.wikipedia.org/wiki/Software_versioning) software to enable
software changes and compatibility of components to be tracked, as well as to
aid with bug tracking and the application of updates. To achieve this, it is
important that we effectively version each source module, binary package and
release.
# Module Versioning
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](#package-versioning) 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](https://autotools.io/libtool/version.html).
To update the libtool version, follow the algorithm given in the comments
below. This is a typical `configure.ac` 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.
AC_SUBST([LT_VERSION],[0:0:0])
```
The following snippet can be used in a `Makefile.am` 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](https://gitlab.apertis.org/pkg/target/apertis-customizations/blob/apertis/v2020dev0/development/build-snapshot)
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]( {{< ref "module_setup.md#parallel-installability" >}} ).
- `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).
# Understanding Binary Build Suffixes
For every binary release (*Developer, Preview, Product*), we add a build suffix
string to the packages, which relates to the release name of Apertis. The
build suffix gets added to every built .deb package. Having a build suffix
helps determine which Apertis release the .deb package was built for.
The suffix string is constructed of: `b<Release_Name>b<B_CNT>`.
- The initial `b` is for backward compatibility ensuring the new suffix string
can work well together with older release packages.
- `<Release_Name>` refers to the Apertis release's name.
- `b<B_CNT>` refers to being a binary build along with the build count.
The build count is incremented each time the package is built, regardless of
whether the source has changed.
For example, for the Apertis Developer Release `v2020dev0` we add the string
`bv2020dev0b1` to the project configuration on OBS when the package is first
built. Similarly, for an Apertis Product Release of `v2019.0` we add the
string `bv2019.0b2` to the project configuration on OBS when it is built for
the second time with no source change.
# Product Point Release Versioning
A product point release rolls the packages previously released in the update and
security repositories into the stable branch. It is required to ensure that the
packages in the new point release have a higher version than the binary package
in the updates or security repositories, it is thus necessary to include the point
releases numbering (e.g. `v2020.1`, `v2020.2`) in the build suffix.
For example, during the initial release of the v2020 release, the build suffix
was `bv2020.0b<B_CNT>`. The same build suffix is inherited by the updates and
security sub-repositories during this time period. Before doing a new point
release *v2020.1*, the build suffix of the main repositories
(`apertis:v2020:target`, `apertis:v2020:development`, `apertis:v2020:sdk`,
`apertis:v2020:hmi` etc) is set to `vb2020.1b<B_CNT>`.
Once this step has been taken, changes previously commited to Apertis update
and security branches (such as `apertis/v2020-updates` and
`apertis/v2020-security`) are merged into the main release branch
(`apertis/v2020`), thus triggering a build and generation of a package with the
required point release suffix. This ensures that the packages synced from the
updates and security sub-repositories have higher versions than packages from
the updates and security sub-repositories. Once the merge has been completed,
the equivalent packages in the update and security branches are purged to allow
these branches to be used for following updates and security fixes to the new
point release.
+++
date = "2019-10-24"
weight = 100
title = "How to Release Packages"
aliases = [
"/guidelines/versioning.md",
"/old-wiki/Guidelines/Versioning",
"/user_joykim/howtoreleasepackages.md",
"/old-wiki/User:Joykim/HowToReleasePackages",
"/old-wiki/Guidelines/HowToReleasePackages"
]
+++
This document aims to explain how to release packages to Apertis
projects.
# Development workflow
Apertis currently deals with two types of packages
- Packages imported from upstream distributions: they live under
[gitlab.apertis.org/pkg/](https://gitlab.apertis.org/pkg/) and
follow the
[Guidelines/Gitlab-based_packaging_workflow]( {{< ref "gitlab-based_packaging_workflow.md" >}} )
- Packages for which Apertis is the upstream: they live under
[appfw](https://gitlab.apertis.org/appfw),
[hmi](https://gitlab.apertis.org/hmi), etc.
# Writing commit messages suitable for generating `debian/changelog` with `gbp-dch`
Commit messages should follow the [recommended
style]( {{< ref "/guidelines/contribution_process.md#commit-message" >}} ).
In addition,
[gbp-dch](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/man.gbp.dch.html)
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:
<code>
Update website link to demo images
The website has new path for demo images.
Gbp-Dch: Full
Apertis: https://phabricator.apertis.org/T12345
Thanks: Mariano for pointing out the issue
Signed-off-by: Héctor Orón Martínez <hector.oron@collabora.co.uk>
</code>
to the following `debian/changelog` entry:
<code>
```
* Update website link to demo images.
The website has new path for demo images.
Signed-off-by: Héctor Orón Martínez <hector.oron@collabora.co.uk>
Thanks to Mariano for pointing out the issue (Apertis: T12345)
```
</code>
Just make sure your package has the following entries in
`debian/gbp.conf`:
<code>
[dch]
ignore-branch = True
meta-closes = Apertis
meta-closes-bugnum = (?:https://phabricator.apertis.org/)?(\T?\d+)
</code>
# 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
/Users/justin/.gnupg/secring.gpg
--------------------------------
sec 2048R/85AC7EE513BFB53B 2017-03-03
uid Justin Kim <justin.kim@collabora.com>
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"
## Versioning
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](#package-versioning) 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](https://autotools.io/libtool/version.html).
To update the libtool version, follow the algorithm given in the
comments below. This is a typical `configure.ac` 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.
AC_SUBST([LT_VERSION],[0:0:0])
The following snippet can be used in a `Makefile.am` 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](https://gitlab.apertis.org/infrastructure/apertis-customizations/blob/apertis/v2020dev0/development/build-snapshot)
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]( {{< ref "module_setup.md#parallel-installability" >}} ).
- `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](https://git.apertis.org) should be released with the
following procedure, roughly based on the [GNOME release
process](https://wiki.gnome.org/MaintainersCorner/Releasing). The
commands below assume you're running the
[Apertis SDK](https://designs.apertis.org/latest/software-development-kit.html).
1. Make sure all the `git-buildpackage` local branches (`apertis/*`,
`upstream/*` and `pristine-tar`) are available and up-to-date:
<code>
$ gbp pull
</code>
2. Choose the new version number by the rules of [Libtool
versioning](#libtool-versioning) and [Package
versioning](#package-versioning)
3. Make sure you have no local changes and you are in right branch
<code>
$ git status
</code>
4. `configure.ac`: 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](#generate-debian.2fchangelog-from-the-git-log-with-gbp-dch)
and mark it for release replacing `UNRELEASED` with the current
version (for instance `16.12`) <code>
$ gbp dch --auto -R
</code>
6. Make sure that all tasks this release is fixing [are
mentioned](https://designs.apertis.org/latest/contribution-process.html#automatically-closing-tasks)
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
`configure.ac`
9. Build test the package with
[`build-snapshot`](https://gitlab.apertis.org/infrastructure/apertis-customizations/blob/apertis/v2020dev0/development/build-snapshot)
<code>
$ build-snapshot localhost
</code>
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. <code>
PACKAGE=$(dpkg-parsechangelog -SSource)
DEBVERSION=$(dpkg-parsechangelog -SVersion)
VERSION=${DEBVERSION%%-*}
RELEASE=$(dpkg-parsechangelog -SDistribution)
COMPONENT=$(cat debian/source/apertis-component)
</code> If `build-snapshot` succeeds, commit the changes. <code>
$ git commit --all --signoff -m "Release $PACKAGE version $DEBVERSION"
</code>
12. Submit a merge request for review following the [contribution
process
guidelines](https://designs.apertis.org/latest/contribution-process.html),
paying special attention to the section about [release
commits](https://designs.apertis.org/latest/contribution-process.html#release-commits)
if you are releasing a new version of the package.
13. Skip this if you are only releasing changes under the `debian/`
folder and not doing an upstream release at the same time:
1. If you're doing an upstream release, tag it (note the versioning
must have a <strong>`v`</strong>, for instance `v1.2.3`). <code>
$ git tag v$VERSION -s -m "Release $PACKAGE $VERSION"
</code>
14. Tag the Apertis release. <code>
$ gbp buildpackage --git-tag --git-tag-only --git-ignore-branch
</code>
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) <code>
$ git push origin v$VERSION apertis/$VERSION
$ git push
</code>
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
- [Autotools Mythbuster guide to library
versioning](https://autotools.io/libtool/version.html)
- [libtool manual page on version
info](http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html)
- [GNOME release process
instructions](https://wiki.gnome.org/MaintainersCorner/Releasing)
......@@ -228,7 +228,7 @@ Whenever a symbol is added to the public API, it should have a documentation
comment added. This comment should always contain a `Since` line with the
package version number of the release which will first contain the new API.
This should be the number currently in `configure.ac` if
[post-release version incrementing]( {{< ref "howtoreleasepackages.md#release-process" >}} )
[post-release version incrementing]( {{< ref "versioning.md#libtool-versioning" >}} )
is being used.
e.g.
......
......@@ -123,42 +123,88 @@ style and formatting to be used:
- the longer
[Linux kernel style guide for commit messages](https://www.kernel.org/doc/html/v4.14/process/submitting-patches.html#describe-your-changes)
A few rules are automatically checked by the Apertis infrastructure:
Minimally the following should be followed:
- Subject: less than 50 characters
- Body: each line should be less than 72 characters long
- A `Signed-off-by` tag must be present as a
[Developer Certificate of Origin](https://developercertificate.org/)
Tags can be used to
[make commit messages suitable for automatically generating `debian/changelog`]( {{< ref "/guidelines/howtoreleasepackages.md#writing-commit-messages-suitable-for-generating-debian/changelog-with-gbp-dch" >}} ).
Here's
[an example](https://git.apertis.org/cgit/canterbury.git/commit/?id=6338e04aeefe):
CbyServiceManager: Instruct systemd to send SIGKILL after 10s
After executing the ExecStop command-line or sending SIGTERM,
by default systemd will wait up to 90 seconds for a service to exit
before it becomes impatient and sends SIGKILL. This seems far too long
for our use-case; wait 10 seconds instead.
The choice of this arbitrary timeout is a trade-off. If it is too
short, applications with a lot of state to serialize to disk might
be killed before they have done so (we'd better hope they're using
crash-safe I/O patterns like g_file_set_contents()). If it is too
long, a user uninstalling an app-bundle will be left waiting
a long time.
When Ribchester calls TerminateBundle (T2696) it will need to wait
a little longer than this; whatever timeout it uses, a broken or
compromised per-user instance of Canterbury would be able to delay
app-bundle upgrade, rollback or removal by up to that long.
Apertis: https://phabricator.apertis.org/T12345
Signed-off-by: Simon McVittie <smcv@collabora.com>
Reviewed-by: Frédéric Dalleau <frederic.dalleau@collabora.co.uk>
Differential Revision: https://phabricator.apertis.org/D7088
```
CbyServiceManager: Instruct systemd to send SIGKILL after 10s
After executing the ExecStop command-line or sending SIGTERM,
by default systemd will wait up to 90 seconds for a service to exit
before it becomes impatient and sends SIGKILL. This seems far too long
for our use-case; wait 10 seconds instead.
The choice of this arbitrary timeout is a trade-off. If it is too
short, applications with a lot of state to serialize to disk might
be killed before they have done so (we'd better hope they're using
crash-safe I/O patterns like g_file_set_contents()). If it is too
long, a user uninstalling an app-bundle will be left waiting
a long time.
When Ribchester calls TerminateBundle (T2696) it will need to wait
a little longer than this; whatever timeout it uses, a broken or
compromised per-user instance of Canterbury would be able to delay
app-bundle upgrade, rollback or removal by up to that long.
Apertis: https://phabricator.apertis.org/T12345
Signed-off-by: Simon McVittie <smcv@collabora.com>
Reviewed-by: Frédéric Dalleau <frederic.dalleau@collabora.co.uk>
Differential Revision: https://phabricator.apertis.org/D7088
```
Tags can be used in commit messages to enhance the information recorded in the
`debian/changelog` by
[gbp-dch](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/man.gbp.dch.html).
`gbp-dch` is a tool that parses the commit messages and automatically turns
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). This is the default.
- `Full` will include the long description in the generated changelog entry
- `Thanks: $SOMEONE` if you want to give kudos to someone
- `Apertis: {$TASK_URL,$TASK_ID}`, is translated to `(Apertis: Txxxx)` in
`debian/changelog` for automated task status tracking
For the last tag to work, the package requires the following entries in
`debian/gbp.conf`:
```
[dch]
meta-closes = Apertis
meta-closes-bugnum = (?:https://phabricator.apertis.org/)?(\T?\d+)
```
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
Apertis: https://phabricator.apertis.org/T12345
Thanks: Mariano for pointing out the issue
Signed-off-by: Héctor Orón Martínez <hector.oron@collabora.co.uk>
```
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 <hector.oron@collabora.co.uk>
Thanks to Mariano for pointing out the issue (Apertis: T12345)
```
# Merging procedure
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment