Make a new release » History » Revision 45
Revision 44 (msuraev, 08/28/2017 10:51 AM) → Revision 45/115 (msuraev, 08/28/2017 10:51 AM)
{{>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 * 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. 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. h3. Library release * modify @*_LIBVERSION@ in @Makefile.am@ as necessary according to TODO-RELEASE file 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 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 [[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 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. h2. How to (re)tag a new release <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. 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>