Project

General

Profile

Make a new release » History » Version 35

msuraev, 08/28/2017 09:17 AM

1 22 msuraev
{{>toc}}
2
3 2 neels
h1. Make a new release
4 1 neels
5 13 msuraev
The efforts to automate the release process are tracked in https://projects.osmocom.org/issues/1861
6
7 17 msuraev
h2. When to make a new release
8 1 neels
9 16 msuraev
Various Osmocom projects depend on others.
10 1 neels
11 28 msuraev
*FIXME:* following part is disputable and should be fixed
12 29 msuraev
13 16 msuraev
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:
14
15 1 neels
Among others, @openbsc@ depends on the libraries built from @libosmocore@, for example @libosmogsm@.
16
As soon as the @libosmogsm@ library gets a new feature used by @openbsc@, like something was added to
17
@gsm_utils.h@, we shall
18 6 neels
* tag a release in @libosmocore@; say if the previous version was 0.1.2, make it at least 0.1.3.
19 1 neels
* and in @openbsc@, require @libosmogsm@ >= 0.1.3 in @configure.ac@
20 16 msuraev
21 28 msuraev
*Proposed policy:*
22 16 msuraev
* master branch is expected to depend on latest master branches of depended-upon projects
23 24 msuraev
* make release of depended-upon projects if necessary before making non-library project release
24
* make sure that we have correct version dependencies before making non-library project release
25 1 neels
26 25 msuraev
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
27 20 msuraev
28 17 msuraev
h2. How to make a new release
29
30 35 msuraev
First we outline specific steps for different project types, than common part. The release helper (installed by @libosmocore-dev@) available via @make release@ takes care of
31 1 neels
32 35 msuraev
* version bump
33
* debian/changelog update
34
* commit
35
* sign
36
* tag
37
38
Feel free to send patches implementing further automation as you see fit.
39
40 17 msuraev
h3. Library release
41 30 msuraev
42 1 neels
* modify @*_LIBVERSION@ in @Makefile.am@ as necessary according to TODO-RELEASE file
43 34 msuraev
44
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.
45 1 neels
46
h3. Non-library release
47
48 35 msuraev
Nothing special is required ATM.
49 1 neels
50 30 msuraev
h3. Common steps
51 1 neels
52 30 msuraev
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.
53 1 neels
54 30 msuraev
* run @make REL=minor release@
55
* inspect the latest commit which was just created
56 32 msuraev
* adjust it if necessary and re-sign (see [[Make_a_new_release#How-to-retag-a-new-release|Re-tag new release]])
57 30 msuraev
* push commit for review using @git review -f@ (see [[Gerrit]] for alternatives)
58
* push the release tag by @git push gerrit --tags@
59 1 neels
60 30 msuraev
h3. How to (re)tag a new release
61 1 neels
62 30 msuraev
* run @git tag -s 0.4.0 -f -m "Release v0.4.0 on 2017-08-25."@
63
64
This will automatically (re)sign the latest commit. You can specify which commit to sign explicitly.
65 3 neels
66 1 neels
Say, for example, the git hash is @012342abcdefg@ and the next open version is 0.1.3:
67 9 neels
<pre>
68 1 neels
git tag -s 0.1.3 012342abcdefg -m "release 0.1.3"
69
</pre>
70 8 neels
71 1 neels
(If @gpg@ complains, see [[Make a new release#GPG-Have-a-matching-user-id|GPG: Have a matching user id]].)
72 4 neels
73 1 neels
Verify that git picks up the new version tag:
74
<pre>
75
$ git describe
76
0.1.3-3-g1f95179
77
</pre>
78 11 neels
79
*For your local build, _nothing will change_ until you delete the @.version@ file
80
and completely rebuild:*
81 1 neels
82
<pre>
83 10 neels
rm .version
84
autoreconf -fi
85 1 neels
./configure
86
make
87
cat .version
88
</pre>
89
90
This should show the same as @git describe@.
91
92
When you're convinced that all is in order, push the new tag:
93
94
<pre>
95
git push origin 0.1.3
96
</pre>
97 14 neels
98 1 neels
If anything went wrong, you can delete the tag (locally) by
99 15 msuraev
<pre>
100 14 neels
git tag -d 0.1.3
101
</pre>
102
and, if you've already pushed it, by
103
<pre>
104
git push --delete origin 0.1.3
105 1 neels
</pre>
106 26 msuraev
107
h2. Deprecation policy
108 27 msuraev
109 26 msuraev
Functions/interfaces marked as deprecated for X releases of type Y can be removed in next Z release.
110 27 msuraev
111 26 msuraev
TBD: what's appropriate value for X? which Y and Z (from major/minor/patch) should we use?
112 1 neels
113
h2. GPG: Have a matching user id
114
115
By default, @git tag -s@ takes your author information to lookup the secret GPG key to sign a tag with.
116
If the author+email do not exactly match one of the key's @uid@s, you will get this error:
117
118
<pre>
119
gpg: signing failed: secret key not available
120
</pre>
121
122
Verify: say, your author+email info in your git config says "John Doe <john@doe.net>", try
123
<pre>
124
gpg --list-secret-keys "John Doe <john@doe.net>"
125
</pre>
126
If this fails, GPG won't find the right key automatically.
127
128
Ways to resolve:
129
130
* Use @git tag -u <key-id>@
131
* Edit your secret key to add a uid that matches your author information
132
<pre>
133
gpg --edit-key john@doe.net
134
gpg> adduid
135
# enter details to match the git author
136
gpg> save
137
</pre>
Add picture from clipboard (Maximum size: 48.8 MB)