Make a new release

The efforts to automate the release process are tracked in

When to make a new release

Various Osmocom projects depend on others.

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 of non-library projects (and corresponding depended-upon libraries):
  • once per XX months?
  • before every OsmoDevCon?
  • once YY items accumulated in TODO-RELEASE file(see TODO-RELEASE file format)
  • when configuration/db format changes?

This would help to avoid batching too many changes together and to adhere to RERO better - see

How to make a new release

First we outline specific steps for different project types, than common part. The helper (installed by libosmocore-dev) available via make release takes care of

  • version bump
  • debian/changelog update
  • commit
  • sign
  • tag

Feel free to send patches implementing further automation as you see fit.

Library release

  • modify *_LIBVERSION in src/ as necessary according to TODO-RELEASE file
  • if necessary ("current" component of *_LIBVERSION was bumped) than rename debian/lib*.install to match the change
  • if necessary (any of debian/lib*.install) were renamed than adjust debian/control accordingly

The release helper is trying to be smart about it and prevent making new library release with non-empty TODO-RELEASE file if *_LIBVERSION is not adjusted beforehand.

Non-library release

Nothing special is required ATM.

Common steps

Be default make release prepares 'patch' release but you can manually specify any of 'major/minor/patch' as necessary - see for details.

  • make REL=minor release
  • inspect the latest commit which was just created
  • adjust it if necessary and re-sign (see Re-tag new release)
  • push commit for review using git review -f (see Gerrit for alternatives)
  • push the release tag by git push gerrit --tags
  • consider preparing article for and sending announcement to appropriate ML for major release once release commit passed the review

Which new release to make

Use following guidelines when choosing release type:
  • major - ?? TBD
  • minor - ?? TBD
  • patch - ?? TBD

If unsure - ask in corresponding ML.

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?

TODO-RELEASE file format and maintenance

  • all the strings which contain # considered comment and will be ignored
  • actual entries consists of 3 tab-separated fields:
    1. library - name of the library affected (should correspond to lib* file in project's root directory)
    2. what - API or ABI change (used as a guidance to properly bump *_LIBVERSION)
    3. description - textual description (will end up in changelog)

When change affecting library's API/ABI is made than new entry should be added to TODO-RELEASE according to the format above. The file will be claned-up automatically by make release command.

How to (re)tag a new release

This might be necessary if previous release was made manually with some mistakes which have to be corrected and amended to the release commit.

git tag -s 0.4.0 -f -m "Release v0.4.0 on 2017-08-25." 

This will automatically (re)sign the latest commit. You can specify which commit to sign explicitly.

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

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

rm .version
autoreconf -fi
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

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 <>" 

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
    gpg> adduid
    # enter details to match the git author
    gpg> save