Project

General

Profile

Make a new release

The efforts to automate the release process are tracked in https://projects.osmocom.org/issues/1861

When to make a new release

Various Osmocom projects depend on others.

FIXME: following part is disputable and should be fixed

As soon as a feature is added to one Osmocom project that is needed for another dependent project to compile, we should tag at least a minor-revision bump in the depended-upon project and require it in the depending project's configure.ac. To illustrate, let's look at this example:

Among others, openbsc depends on the libraries built from libosmocore, for example libosmogsm.
As soon as the libosmogsm library gets a new feature used by openbsc, like something was added to
gsm_utils.h, we shall
  • tag a release in libosmocore; say if the previous version was 0.1.2, make it at least 0.1.3.
  • and in openbsc, require libosmogsm >= 0.1.3 in configure.ac
Proposed policy:
  • master branch is expected to depend on latest master branches of depended-upon projects
  • make release of depended-upon projects if necessary before making non-library project release
  • make sure that we have correct version dependencies before making non-library project release

Alternatively/additionally we can make timely releases (once per XX months? before every OsmoDevCon?) of non-library projects (and corresponding depended-upon libraries) to avoid batching too many changes together and to adhere to RERO better - see http://scalare.org/wp-content/uploads/2015/06/2015-Why-and-HowShould-OpenSource-ProjectsAdopt-Time-Based-Releases.pdf

How to make a new release

Library release

Commit changes:
  • cleanup TODO-RELEASE file if not empty, bumping API versions accordingly (see comments in TODO-RELEASE)
  • update debian/changelog using gbp dch --debian-tag='%(version)s' --auto command

Non-library release

TODO: more detailed description of necessary release steps:
create, sign, publish tarball, pushing via gerrit etc.

How to tag a new release

The revision to tag must be merged to the public, upstream master branch.

Find out the git hash for the revision you want to tag.

Find out the next open version number. Take care: look at all of these:
  • git tag -l
  • debian/changelog
    For example, the changelog may contain versions that were forgotten to be tagged.

Now, make a GPG-signed tag of that git hash with the next open version number.

Say, for example, the git hash is 012342abcdefg and the next open version is 0.1.3:

git tag -s 0.1.3 012342abcdefg -m "release 0.1.3" 

(If gpg complains, see GPG: Have a matching user id.)

Verify that git picks up the new version tag:

$ git describe
0.1.3-3-g1f95179

For your local build, nothing will change until you delete the .version file
and completely rebuild:

rm .version
autoreconf -fi
./configure
make
cat .version

This should show the same as git describe.

When you're convinced that all is in order, push the new tag:

git push origin 0.1.3

If anything went wrong, you can delete the tag (locally) by

git tag -d 0.1.3

and, if you've already pushed it, by
git push --delete origin 0.1.3

Deprecation policy

Functions/interfaces marked as deprecated for X releases of type Y can be removed in next Z release.

TBD: what's appropriate value for X? which Y and Z (from major/minor/patch) should we use?

GPG: Have a matching user id

By default, git tag -s takes your author information to lookup the secret GPG key to sign a tag with.
If the author+email do not exactly match one of the key's @uid@s, you will get this error:

gpg: signing failed: secret key not available

Verify: say, your author+email info in your git config says "John Doe <>", try

gpg --list-secret-keys "John Doe <john@doe.net>" 

If this fails, GPG won't find the right key automatically.

Ways to resolve:

  • Use git tag -u <key-id>
  • Edit your secret key to add a uid that matches your author information
    gpg --edit-key john@doe.net
    gpg> adduid
    # enter details to match the git author
    gpg> save