Cellular Network Infrastructure

{{>toc}}

h1. Make a new release

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

h2. 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

h2. How to make a new release

h3. 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

h3. Non-library release

TODO: more detailed description of necessary release steps:

create, sign, publish tarball, pushing via gerrit etc.

h3. 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:

<pre>

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

</pre>

(If @gpg@ complains, see [[Make a new release#GPG-Have-a-matching-user-id|GPG: Have a matching user id]].)

Verify that git picks up the new version tag:

<pre>

$ git describe

0.1.3-3-g1f95179

</pre>

*For your local build, _nothing will change_ until you delete the @.version@ file

and completely rebuild:*

<pre>

rm .version

autoreconf -fi

./configure

make

cat .version

</pre>

This should show the same as @git describe@.

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

<pre>

git push origin 0.1.3

</pre>

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

<pre>

git tag -d 0.1.3

</pre>

and, if you've already pushed it, by

<pre>

git push --delete origin 0.1.3

</pre>

h2. 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?

h2. 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:

<pre>

gpg: signing failed: secret key not available

</pre>

Verify: say, your author+email info in your git config says "John Doe <john@doe.net>", try

<pre>

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

</pre>

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

<pre>

gpg --edit-key john@doe.net

gpg> adduid

# enter details to match the git author

gpg> save

</pre>