Project

General

Profile

Make a new release » History » Version 110

fixeria, 08/10/2022 08:29 PM
added libosmo-gprs

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 76 osmith
This would help to avoid batching too many changes together and to adhere to RERO better - see "2015-Why-and-HowShould-OpenSource-ProjectsAdopt-Time-Based-Releases.pdf":https://www.researchgate.net/publication/268815678_Why_and_How_Should_Open_Source_Projects_Adopt_Time-Based_Releases
23 20 msuraev
24 61 pespin
h2. Versioning considerations for libraries
25 1 neels
26 62 pespin
Every osmocom library is built using libtool's version-info system. This system format and algorithm to update the versions is documented in "here":https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html#Updating-version-info.
27 1 neels
28 62 pespin
However, debian packaging system follows a different versioning convention, but conveniently the debian versioning system can be deduced from libtool's version-info. More information can be found in "here":https://autotools.io/libtool/version.html.
29 61 pespin
Specially interesting is the warning section:
30
31 62 pespin
> A common mistake is to assume that the three values passed to -version-info map directly into the three numbers at the end of the library name. This is not the case, and indeed, current, revision and age are applied differently depending on the operating system that one is using.
32
> For Linux, for instance, while the last two values map directly from the command-line, the first is calculated by subtracting age from current. On the other hand, on modern FreeBSD, only one component is used in the library version, which corresponds to current. 
33
34
More related information on the version translation procedure can be found here: "[1]":https://github.com/haskell/cabal/issues/4052#issuecomment-258044949 "[2]":https://stackoverflow.com/questions/36734105/how-is-the-version-number-in-library-names-generated
35 52 pespin
36 61 pespin
Summary: For libtool's system @current:revision:age@, it gets translated into version number @major.age.revision@, where @major=current-age@, reflecting the fact that ABIs can be backwards compatible. Debian uses @major@ to generate the package name.
37
38 1 neels
The following command, when run on a shared library, will output the name to be used for the Debian package containing that shared library:
39 71 pespin
<pre>
40 70 pespin
objdump -p library.so \
41
    | sed -n -e's/^[[:space:]]*SONAME[[:space:]]*//p' \
42
    | LC_ALL=C sed -r -e's/([0-9])\.so\./\1-/; s/\.so(\.|$)//; y/_/-/; s/(.*)/\L&/'
43
</pre>
44
45 61 pespin
h2. osmocom-release.mk
46
47
The @osmo-release.mk@ helper (installed by @libosmocore-dev@) available via @make release@ takes care of
48
49 35 msuraev
* version bump
50 57 pespin
* debian/changelog update
51
* commit
52 1 neels
* sign
53 57 pespin
* tag
54 1 neels
55
Feel free to send patches implementing further automation as you see fit.
56
57
You can alternatively run osmo-release.mk directly from your git repo in /foo/bar/libosmocore by using:
58 92 pespin
<pre>
59
PATH="$PATH:/foo/bar/libosmocore" make REL=minor release --include-dir="/foo/bar/libosmocore"
60
</pre>
61 1 neels
62 61 pespin
h3. Dependencies
63 1 neels
64 61 pespin
The @osmo-release.mk@ requires several extra dependencies. Make sure you have them installed in your system:
65
* bumpversion
66
* git-buildpackage
67
* devscripts
68
69
h3. TODO-RELEASE file format and maintenance
70
71
* all the strings which contain @#@ considered comment and will be ignored
72
* actual entries consists of 3 tab-separated fields:
73
# library - name of the library affected (should correspond to @lib*.pc.in@ file in project's root directory)
74
# what - API or ABI change (used as a guidance to properly bump @*_LIBVERSION@)
75
# description - textual description (will end up in changelog)
76
77
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.
78
79
h2. How to make a new release
80
81
First we outline specific steps for different project types, then common part.
82 86 pespin
* Grep for @PKG_CHECK_MODULES@ in @configure.ac@, and build with dependencies listed there (check versions after @>=@). If cannot compile, adjust the versions there so compilation works. eg: @osmo-ci.git/scripts/osmo-depcheck.py -w /tmp/depcheck -b -j 8 -u /home/$USER/where-my-local-git-repos-are/ osmo-ggsn@
83 82 pespin
* Adjust dependency versions in @debian/control@ (under @Build-Depends@) to match those of configure.ac
84 93 pespin
* Adjust dependency version in @contrib/*.spec.in@ to match those of configure.ac
85 84 pespin
* Make sure patches under @debian/patches@ still apply correctly.
86 61 pespin
87
h3. Extra steps for Libraries
88
89 1 neels
Some extra previous steps are required if the project installs a public shared library.
90
91 82 pespin
* modify @*_LIBVERSION@ in @src/Makefile.am@ as necessary according to TODO-RELEASE file. Usually the easiest is using @git diff $OLD_RELEASE -- include/foobar/@ to check API/ABI changes, and implementation changes similarly with @git diff $OLD_RELEASE -- src/foobar/@
92
* if necessary ("@major = current - age@" component of @*LIBVERSION@ was bumped, package name changing as a result) then:
93
** Rename @debian/lib*.install@ to match the name change. See [[Make_a_new_release#Versioning-considerations-for-libraries|Versioning considerations for libraries]].
94 97 pespin
** Adjust package names in @contrib/*.spec.in@ accordingly.
95 82 pespin
** Adjust package names in @debian/control@ accordingly. Specifically look for "Package" and "Depends" attributes.
96
** Some projects containing both binaries and libraries (@osmo-ggsn@, @libosmo-sccp@) also state the library version in dh_strip lines in @debian/rules@. That one needs to be updated too to match the new library version.
97 32 msuraev
98 98 pespin
Upon major libversion change ("old_major" -> "new_major"), the change pattern in general follow this structure:
99
* @"s/${libname}${old_major}/${libname}${new_major}/g"@
100
* @"s/${libname}.so.${old_major}/${libname}.so.${new_major}/g"@
101
102 30 msuraev
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.
103
104 61 pespin
h3. Release steps
105 1 neels
106 44 msuraev
By default @make release@ prepares 'patch' release but you can manually specify any of 'major/minor/patch' as necessary - see http://semver.org/ for details.
107
108 99 osmith
* Run @git fetch --tags@ to ensure your local copy of the repository has the latest tags.
109 77 osmith
* Create a new branch from where you would like to create a new release (master or a previous release) and name it @yourname/release@
110 83 pespin
* Make sure all the manual changes you want in the release commit are staged (@git add@), (see previous sections about changes needed).
111 78 osmith
* Run @make REL=minor release@
112 64 pespin
* an editor will be opened in case you want to reword the release commit. Useful if you want to add any remarks on the actions taken.
113 44 msuraev
* inspect the latest commit which was just created
114 1 neels
* adjust it if necessary and re-sign (see [[Make_a_new_release#How-to-retag-a-new-release|Re-tag new release]])
115 74 pespin
* push commit for review to gerrit and ask somebody to review and merge it quickly (to avoid other commits being merged in between).
116 77 osmith
* Once merged, make sure the merged release commit did not change (due to in-between merges), then push the release tag with @git push gerrit --tags@
117 1 neels
* consider preparing article for https://osmocom.org/news/ and sending announcement to appropriate ML for major release once release commit passed the review
118 64 pespin
119
In case you want to undo the release commit you did locally:
120
* @git tag -d TAG_JUST_CREATED@
121
* @git reset --soft HEAD^@
122 94 pespin
* @git restore --staged debian/changelog && git restore debian/changelog@
123 64 pespin
* Do your modifications
124
* Proceed again with the release steps listed above
125 45 msuraev
126 107 osmith
In case there is no @make release@ target (e.g. osmo_dia2gsup):
127
* run @gbp dch@
128
* adjust debian/changelog, at least change UNRELEASED to unstable
129
* commit as "Bump version: 0.1.1" (replace 0.1.1 with new version)
130 108 osmith
* run @git tag -s 0.1.1@, put as title "Release 0.1.1"
131 107 osmith
132 45 msuraev
h2. Which new release to make
133
134
Use following guidelines when choosing release type:
135
* major - ?? TBD
136
* minor - ?? TBD
137 43 msuraev
* patch - ?? TBD
138 1 neels
139 43 msuraev
If unsure - ask in corresponding ML.
140
141
h2. Deprecation policy
142
143
Functions/interfaces marked as deprecated for X releases of type Y can be removed in next Z release.
144
145 55 pespin
TBD: what's appropriate value for X? which Y and Z (from major/minor/patch) should we use?
146 43 msuraev
147
h2. How to (re)tag a new release
148
149 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.
150
151 36 msuraev
<pre>
152
git tag -s 0.4.0 -f -m "Release v0.4.0 on 2017-08-25."
153
</pre>
154 30 msuraev
155
This will automatically (re)sign the latest commit. You can specify which commit to sign explicitly.
156 3 neels
157 1 neels
Say, for example, the git hash is @012342abcdefg@ and the next open version is 0.1.3:
158 9 neels
<pre>
159 1 neels
git tag -s 0.1.3 012342abcdefg -m "release 0.1.3"
160
</pre>
161 8 neels
162 1 neels
(If @gpg@ complains, see [[Make a new release#GPG-Have-a-matching-user-id|GPG: Have a matching user id]].)
163 4 neels
164 1 neels
Verify that git picks up the new version tag:
165
<pre>
166
$ git describe
167
0.1.3-3-g1f95179
168
</pre>
169 11 neels
170 42 msuraev
N. B: *For your local build, _nothing will change_ until you delete the @.version@ file and completely rebuild:*
171 1 neels
172
<pre>
173 10 neels
rm .version
174
autoreconf -fi
175 1 neels
./configure
176
make
177
cat .version
178
</pre>
179
180
This should show the same as @git describe@.
181
182
When you're convinced that all is in order, push the new tag:
183
184
<pre>
185
git push origin 0.1.3
186
</pre>
187 14 neels
188 1 neels
If anything went wrong, you can delete the tag (locally) by
189 15 msuraev
<pre>
190 42 msuraev
git tag -d 0.1.3
191
</pre>
192
and, if you've already pushed it, by
193
<pre>
194
git push --delete origin 0.1.3
195
</pre>
196 1 neels
197
h2. GPG: Have a matching user id
198
199
By default, @git tag -s@ takes your author information to lookup the secret GPG key to sign a tag with.
200
If the author+email do not exactly match one of the key's @uid@s, you will get this error:
201
202
<pre>
203
gpg: signing failed: secret key not available
204
</pre>
205
206
Verify: say, your author+email info in your git config says "John Doe <john@doe.net>", try
207
<pre>
208
gpg --list-secret-keys "John Doe <john@doe.net>"
209
</pre>
210
If this fails, GPG won't find the right key automatically.
211
212
Ways to resolve:
213
214
* Use @git tag -u <key-id>@
215
* Edit your secret key to add a uid that matches your author information
216
<pre>
217
gpg --edit-key john@doe.net
218
gpg> adduid
219
# enter details to match the git author
220
gpg> save
221
</pre>
222 56 pespin
223 106 neels
h2. GPG: failed to sign
224
225
If you are seeing this error:
226
227
<pre>
228
$ git tag ...
229
error: gpg failed to sign the data
230
error: unable to sign the tag
231
</pre>
232
233
you may need to set this in your terminal's environment:
234
235
<pre>
236
export GPG_TTY=$(tty)
237
</pre>
238
239
Furthermore, for headless operation (remote server) it may be necessary to direct the GPG key entry to the terminal.
240
On debian, make sure the curses key entry is installed:
241
<pre>
242
apt-get install pinentry-curses
243
</pre>
244
245
and possibly also uninstall other pinentry alternatives, or otherwise make sure it is not trying to launch a graphical pinentry.
246
247 87 laforge
h1. Creating a patch release
248
249 89 pespin
Sometimes we want to create a patch release to apply an important fix to an older major/minor release. Assuming you're in libosmocore and want to create 1.3.1 off 1.3.0, this works as follows:
250 87 laforge
251 90 pespin
# (Locally checkout 1.3.0 as a new branch called rel-1.3.1)
252 88 laforge
<pre>
253
git checkout -b rel-1.3.1 1.3.0
254
</pre>
255 90 pespin
# Create a rel-1.3.1 branch in gerrit
256 88 laforge
<pre>
257
git push gerrit rel-1.3.1:refs/heads/rel-1.3.1
258
</pre>
259 90 pespin
# Do whatever local modifications such as cherry-picking of fixes, ...
260
# Perform the release process as outlined above, using 'REL=patch'
261 88 laforge
<pre>
262
make REL=patch release
263 1 neels
</pre>
264 90 pespin
# Push the changes for review to the rel-1.3.1 branch
265 88 laforge
<pre>
266 1 neels
git push gerrit HEAD:refs/for/rel-1.3.1
267 88 laforge
</pre>
268 90 pespin
# Perform gerrit review, merge patches in gerrit UI
269
# Do @git fetch gerrit@ and make sure your local branch with your tag points to the remote one (eg @gitk --all@ or @git show@).
270
# Push the tag to the repo, *after the patches were merged* to that branch
271 88 laforge
<pre>
272
git push gerrit 1.3.1
273
</pre>
274 90 pespin
# Remove the temporary branch
275 88 laforge
<pre>
276
git push gerrit :rel-1.3.1
277
</pre>
278 56 pespin
279
h1. Dependency graph
280
281
This section aims at providing a dependency graph of the osmocom cellular network infrastructure projects in case a cascade of releases is intended:
282 66 pespin
283 56 pespin
{{graphviz_link()
284
digraph G {
285
    libusrp -> {osmo_trx};
286 105 pespin
    libas1nc -> {osmo_iuh, osmo_msc, openbsc, osmo_hnodeb, osmo_hnbgw};
287 85 pespin
    libsmpp34 -> {osmo_msc, openbsc};
288 60 pespin
    libgtpnl -> {osmo_ggsn};
289 110 fixeria
    libosmocore -> {libosmo_abis, libosmo_gprs, libosmo_netif, libosmo_sccp, libosmo_pfcp, osmo_iuh, osmo_ggsn, osmo_sgsn, osmo_mgw, osmo_msc, osmo_hlr, osmo_bsc, osmo_bts, osmo_pcu, osmo_trx, openbsc, osmo_sip_connector, osmo_pcap, osmo_gbproxy, osmo_hnodeb, osmo_hnbgw, osmo_cbc, osmo_smlc, osmo_uecups};
290 56 pespin
    osmo_gsm_manuals -> {osmo_pcu, osmo_trx, osmo_sip_connector, osmo_hlr, libosmo_sccp, osmo_sgsn, osmo_bsc, osmo_ggsn, osmo_msc, osmo_mgw, osmo_bts};
291 1 neels
    libosmo_abis -> {libosmo_netif, osmo_sgsn, osmo_msc, osmo_hlr, osmo_bsc, osmo_mgw, osmo_bts, openbsc, osmo_hnodeb};
292 110 fixeria
    libosmo_gprs -> {osmo_pcu};
293 105 pespin
    libosmo_netif -> {libosmo_sccp, osmo_iuh, osmo_sgsn, osmo_mgw, osmo_msc, osmo_bsc, openbsc, osmo_hnodeb, osmo_hnbgw, osmo_cbc, osmo_uecups};
294 1 neels
    libosmo_sccp -> {osmo_iuh, osmo_sgsn, osmo_msc, osmo_bsc, openbsc, osmo_hnodeb, osmo_hnbgw, osmo_smlc};
295 109 pespin
    libosmo_pfcp -> {osmo_hnbgw};
296 105 pespin
    osmo_iuh -> {osmo_msc, osmo_sgsn, openbsc, osmo_hnodeb, osmo_hnbgw};
297 56 pespin
    osmo_ggsn -> {osmo_sgsn};
298
    osmo_mgw -> {osmo_msc, osmo_bsc};
299 1 neels
    osmo_hlr -> {osmo_msc, osmo_sgsn};
300
}
301
}}
Add picture from clipboard (Maximum size: 48.8 MB)