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.

*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 [[Make_a_new_release#TODO-RELEASE-file-format-and-maintenance|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

h2. Dependencies

The @osmo-release.mk@ requires several extra dependencies. Make sure you have them installed in your system:

* bumpversion

* git-buildpackage

* devscripts

h2. How to make a new release

First we outline specific steps for different project types, then 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.

You can alternatively run osmo-release.mk directly from your git repo in /foo/bar/libosmocore by using:

@PATH="$PATH:/foo/bar/libosmocore" make REL=minor release --include-dir="/foo/bar/libosmocore"@

h3. Library release

* modify @*_LIBVERSION@ in @src/Makefile.am@ as necessary according to TODO-RELEASE file

* if necessary ("current" component of @*_LIBVERSION@ was bumped) then rename @debian/lib*.install@ to match the change

* if necessary (any of @debian/lib*.install@ were renamed) then 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.

h3. Non-library release

Nothing special is required ATM.

h3. Common steps

By default @make release@ prepares 'patch' release but you can manually specify any of 'major/minor/patch' as necessary - see http://semver.org/ for details.

* Add changelog entries for the new version in @TODO-RELEASE@, they will be populated into @debian/changelog@ by @osmo-release.sh@.

* @make REL=minor release@

* inspect the latest commit which was just created

* adjust it if necessary and re-sign (see [[Make_a_new_release#How-to-retag-a-new-release|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

h2. Which new release to make

Use following guidelines when choosing release type:

* major - ?? TBD

* minor - ?? TBD

* patch - ?? TBD

If unsure - ask in corresponding ML.

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. 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.in@ file in project's root directory)

# what - API or ABI change (used as a guidance to properly bump @*_LIBVERSION@)

# description - textual description (will end up in changelog)

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

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

<pre>

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

</pre>

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:

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

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

h2. Dependency graph

This section aims at providing a dependency graph of the osmocom cellular network infrastructure projects in case a cascade of releases is intended:

{{graphviz_link()

digraph G {

    libas1nc -> {osmo_iuh, osmo_msc, openbsc};

    libsmpp34 -> {osmo_msc, openbsc};

    libgtpnl -> {osmo_ggsn};

    libosmocore -> {libosmo_abis, libosmo_netif, libosmo_sccp, osmo_iuh, osmo_ggsn, osmo_sgsn, osmo_mgw, osmo_msc, osmo_hlr, osmo_bsc, osmo_bts, osmo_pcu, osmo_trx, openbsc};

    libosmo_abis -> {libosmo_netif, osmo_sgsn, osmo_msc, osmo_hlr, osmo_bsc, osmo_bts, oepnbsc};

    libosmo_netif -> {libosmo_sccp, osmo_iuh, osmo_sgsn, osmo_mgw, osmo_msc, osmo_bsc, openbsc};

    libosmo_sccp -> {osmo_iuh, osmo_sgsn, osmo_msc, osmo_bsc, openbsc};

    osmo_iuh -> {osmo_msc, openbsc};

    osmo_ggsn -> {osmo_sgsn};

    osmo_mgw -> {osmo_msc, osmo_bsc};

}

}}