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.

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 http://scalare.org/wp-content/uploads/2015/06/2015-Why-and-HowShould-OpenSource-ProjectsAdopt-Time-Based-Releases.pdf

How to make a new release

First we outline specific steps for different project types, than common part. The osmo-release.mk 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/Makefile.am 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 http://semver.org/ 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 https://osmocom.org/news/ 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*.pc.in 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
0.1.3-3-g1f95179

N. B: 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

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