Project

General

Profile

Make a new release » History » Version 56

pespin, 05/02/2018 10:08 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 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 52 pespin
h2. Dependencies
25
26
The @osmo-release.mk@ requires several extra dependencies. Make sure you have them installed in your system:
27
* bumpversion
28
* git-buildpackage
29 53 pespin
* devscripts
30 52 pespin
31 17 msuraev
h2. How to make a new release
32
33 54 pespin
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
34 1 neels
35 35 msuraev
* version bump
36
* debian/changelog update
37
* commit
38
* sign
39
* tag
40
41
Feel free to send patches implementing further automation as you see fit.
42
43 17 msuraev
h3. Library release
44 30 msuraev
45 48 msuraev
* modify @*_LIBVERSION@ in @src/Makefile.am@ as necessary according to TODO-RELEASE file
46 50 pespin
* if necessary ("current" component of @*_LIBVERSION@ was bumped) then rename @debian/lib*.install@ to match the change
47 51 pespin
* if necessary (any of @debian/lib*.install@ were renamed) then adjust @debian/control@ accordingly
48 34 msuraev
49
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.
50 1 neels
51
h3. Non-library release
52
53 35 msuraev
Nothing special is required ATM.
54 1 neels
55 30 msuraev
h3. Common steps
56 1 neels
57 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.
58 1 neels
59 36 msuraev
* @make REL=minor release@
60 30 msuraev
* inspect the latest commit which was just created
61 32 msuraev
* adjust it if necessary and re-sign (see [[Make_a_new_release#How-to-retag-a-new-release|Re-tag new release]])
62 30 msuraev
* push commit for review using @git review -f@ (see [[Gerrit]] for alternatives)
63
* push the release tag by @git push gerrit --tags@
64 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
65 1 neels
66 44 msuraev
h2. Which new release to make
67
68
Use following guidelines when choosing release type:
69
* major - ?? TBD
70
* minor - ?? TBD
71
* patch - ?? TBD
72
73
If unsure - ask in corresponding ML.
74
75 45 msuraev
h2. Deprecation policy
76
77
Functions/interfaces marked as deprecated for X releases of type Y can be removed in next Z release.
78
79
TBD: what's appropriate value for X? which Y and Z (from major/minor/patch) should we use?
80
81 43 msuraev
h2. TODO-RELEASE file format and maintenance
82 1 neels
83 43 msuraev
* all the strings which contain @#@ considered comment and will be ignored
84
* actual entries consists of 3 tab-separated fields:
85
# library - name of the library affected (should correspond to @lib*.pc.in@ file in project's root directory)
86
# what - API or ABI change (used as a guidance to properly bump @*_LIBVERSION@)
87
# description - textual description (will end up in changelog)
88
89 55 pespin
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.
90 43 msuraev
91
h2. How to (re)tag a new release
92
93 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.
94
95 36 msuraev
<pre>
96
git tag -s 0.4.0 -f -m "Release v0.4.0 on 2017-08-25."
97
</pre>
98 30 msuraev
99
This will automatically (re)sign the latest commit. You can specify which commit to sign explicitly.
100 3 neels
101 1 neels
Say, for example, the git hash is @012342abcdefg@ and the next open version is 0.1.3:
102 9 neels
<pre>
103 1 neels
git tag -s 0.1.3 012342abcdefg -m "release 0.1.3"
104
</pre>
105 8 neels
106 1 neels
(If @gpg@ complains, see [[Make a new release#GPG-Have-a-matching-user-id|GPG: Have a matching user id]].)
107 4 neels
108 1 neels
Verify that git picks up the new version tag:
109
<pre>
110
$ git describe
111
0.1.3-3-g1f95179
112
</pre>
113 11 neels
114 42 msuraev
N. B: *For your local build, _nothing will change_ until you delete the @.version@ file and completely rebuild:*
115 1 neels
116
<pre>
117 10 neels
rm .version
118
autoreconf -fi
119 1 neels
./configure
120
make
121
cat .version
122
</pre>
123
124
This should show the same as @git describe@.
125
126
When you're convinced that all is in order, push the new tag:
127
128
<pre>
129
git push origin 0.1.3
130
</pre>
131 14 neels
132 1 neels
If anything went wrong, you can delete the tag (locally) by
133 15 msuraev
<pre>
134 42 msuraev
git tag -d 0.1.3
135
</pre>
136
and, if you've already pushed it, by
137
<pre>
138
git push --delete origin 0.1.3
139
</pre>
140 1 neels
141
h2. GPG: Have a matching user id
142
143
By default, @git tag -s@ takes your author information to lookup the secret GPG key to sign a tag with.
144
If the author+email do not exactly match one of the key's @uid@s, you will get this error:
145
146
<pre>
147
gpg: signing failed: secret key not available
148
</pre>
149
150
Verify: say, your author+email info in your git config says "John Doe <john@doe.net>", try
151
<pre>
152
gpg --list-secret-keys "John Doe <john@doe.net>"
153
</pre>
154
If this fails, GPG won't find the right key automatically.
155
156
Ways to resolve:
157
158
* Use @git tag -u <key-id>@
159
* Edit your secret key to add a uid that matches your author information
160
<pre>
161
gpg --edit-key john@doe.net
162
gpg> adduid
163
# enter details to match the git author
164
gpg> save
165
</pre>
166 56 pespin
167
h2. Dependency graph
168
169
This section aims at providing a dependency graph of the osmocom cellular network infrastructure projects in case a cascade of releases is intended:
170
171
{{graphviz_link()
172
digraph G {
173
    libas1nc -> {osmo_iuh, osmo_msc, openbsc};
174
    libsmpp34 -> {osmo_msc, openbsc};
175
    libgtpnl -> {osmo_ggsn};
176
    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};
177
    libosmo_abis -> {libosmo_netif, osmo_sgsn, osmo_msc, osmo_hlr, osmo_bsc, osmo_bts, oepnbsc};
178
    libosmo_netif -> {libosmo_sccp, osmo_iuh, osmo_sgsn, osmo_mgw, osmo_msc, osmo_bsc, openbsc};
179
    libosmo_sccp -> {osmo_iuh, osmo_sgsn, osmo_msc, osmo_bsc, openbsc};
180
    osmo_iuh -> {osmo_msc, openbsc};
181
    osmo_ggsn -> {osmo_sgsn};
182
    osmo_mgw -> {osmo_msc, osmo_bsc};
183
}
184
}}
Add picture from clipboard (Maximum size: 48.8 MB)