Project

General

Profile

Make a new release » History » Version 50

pespin, 03/05/2018 01:30 PM

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