Project

General

Profile

Make a new release » History » Version 44

msuraev, 08/28/2017 10:51 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
*Proposed policy:*
12 16 msuraev
* master branch is expected to depend on latest master branches of depended-upon projects
13 24 msuraev
* make release of depended-upon projects if necessary before making non-library project release
14
* make sure that we have correct version dependencies before making non-library project release
15 1 neels
16 41 msuraev
Alternatively/additionally we can make timely releases of non-library projects (and corresponding depended-upon libraries):
17
* once per XX months?
18
* before every OsmoDevCon?
19
* once YY items accumulated in TODO-RELEASE file
20
* when configuration/db format changes?
21
22
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
23 20 msuraev
24 17 msuraev
h2. How to make a new release
25
26 39 msuraev
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
27 1 neels
28 35 msuraev
* version bump
29
* debian/changelog update
30
* commit
31
* sign
32
* tag
33
34
Feel free to send patches implementing further automation as you see fit.
35
36 17 msuraev
h3. Library release
37 30 msuraev
38 1 neels
* modify @*_LIBVERSION@ in @Makefile.am@ as necessary according to TODO-RELEASE file
39 34 msuraev
40
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.
41 1 neels
42
h3. Non-library release
43
44 35 msuraev
Nothing special is required ATM.
45 1 neels
46 30 msuraev
h3. Common steps
47 1 neels
48 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.
49 1 neels
50 36 msuraev
* @make REL=minor release@
51 30 msuraev
* inspect the latest commit which was just created
52 32 msuraev
* adjust it if necessary and re-sign (see [[Make_a_new_release#How-to-retag-a-new-release|Re-tag new release]])
53 30 msuraev
* push commit for review using @git review -f@ (see [[Gerrit]] for alternatives)
54
* push the release tag by @git push gerrit --tags@
55 38 msuraev
* consider preparing article for https://osmocom.org/news/ and sending announcement to appropriate ML for major release once release commit passed the review
56 1 neels
57 44 msuraev
h2. Which new release to make
58
59
Use following guidelines when choosing release type:
60
* major - ?? TBD
61
* minor - ?? TBD
62
* patch - ?? TBD
63
64
If unsure - ask in corresponding ML.
65
66 43 msuraev
h2. TODO-RELEASE file format and maintenance
67 1 neels
68 43 msuraev
* all the strings which contain @#@ considered comment and will be ignored
69
* actual entries consists of 3 tab-separated fields:
70
# library - name of the library affected (should correspond to @lib*.pc.in@ file in project's root directory)
71
# what - API or ABI change (used as a guidance to properly bump @*_LIBVERSION@)
72
# description - textual description (will end up in changelog)
73
74
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.
75
76
h2. How to (re)tag a new release
77
78 36 msuraev
<pre>
79
git tag -s 0.4.0 -f -m "Release v0.4.0 on 2017-08-25."
80
</pre>
81 30 msuraev
82
This will automatically (re)sign the latest commit. You can specify which commit to sign explicitly.
83 3 neels
84 1 neels
Say, for example, the git hash is @012342abcdefg@ and the next open version is 0.1.3:
85 9 neels
<pre>
86 1 neels
git tag -s 0.1.3 012342abcdefg -m "release 0.1.3"
87
</pre>
88 8 neels
89 1 neels
(If @gpg@ complains, see [[Make a new release#GPG-Have-a-matching-user-id|GPG: Have a matching user id]].)
90 4 neels
91 1 neels
Verify that git picks up the new version tag:
92
<pre>
93
$ git describe
94
0.1.3-3-g1f95179
95
</pre>
96 11 neels
97 42 msuraev
N. B: *For your local build, _nothing will change_ until you delete the @.version@ file and completely rebuild:*
98 1 neels
99
<pre>
100 10 neels
rm .version
101
autoreconf -fi
102 1 neels
./configure
103
make
104
cat .version
105
</pre>
106
107
This should show the same as @git describe@.
108
109
When you're convinced that all is in order, push the new tag:
110
111
<pre>
112
git push origin 0.1.3
113
</pre>
114 14 neels
115 1 neels
If anything went wrong, you can delete the tag (locally) by
116 15 msuraev
<pre>
117 14 neels
git tag -d 0.1.3
118 1 neels
</pre>
119 42 msuraev
and, if you've already pushed it, by
120
<pre>
121
git push --delete origin 0.1.3
122
</pre>
123
124
h2. Deprecation policy
125
126
Functions/interfaces marked as deprecated for X releases of type Y can be removed in next Z release.
127
128
TBD: what's appropriate value for X? which Y and Z (from major/minor/patch) should we use?
129 1 neels
130
h2. GPG: Have a matching user id
131
132
By default, @git tag -s@ takes your author information to lookup the secret GPG key to sign a tag with.
133
If the author+email do not exactly match one of the key's @uid@s, you will get this error:
134
135
<pre>
136
gpg: signing failed: secret key not available
137
</pre>
138
139
Verify: say, your author+email info in your git config says "John Doe <john@doe.net>", try
140
<pre>
141
gpg --list-secret-keys "John Doe <john@doe.net>"
142
</pre>
143
If this fails, GPG won't find the right key automatically.
144
145
Ways to resolve:
146
147
* Use @git tag -u <key-id>@
148
* Edit your secret key to add a uid that matches your author information
149
<pre>
150
gpg --edit-key john@doe.net
151
gpg> adduid
152
# enter details to match the git author
153
gpg> save
154
</pre>
Add picture from clipboard (Maximum size: 48.8 MB)