- Make a new release
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
- 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
Feel free to send patches implementing further automation as you see fit.
src/Makefile.amas necessary according to TODO-RELEASE file
- if necessary ("current" component of
*_LIBVERSIONwas bumped) than rename
debian/lib*.installto match the change
- if necessary (any of
debian/lib*.install) were renamed than adjust
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.
Nothing special is required ATM.
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.
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:
- library - name of the library affected (should correspond to
lib*.pc.infile in project's root directory)
- what - API or ABI change (used as a guidance to properly bump
- 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"
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
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¶
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 <email@example.com>", try
gpg --list-secret-keys "John Doe <firstname.lastname@example.org>"
If this fails, GPG won't find the right key automatically.
Ways to resolve:
git tag -u <key-id>
- Edit your secret key to add a uid that matches your author information
gpg --edit-key email@example.com gpg> adduid # enter details to match the git author gpg> save