Project

General

Profile

Make a new release » History » Version 89

pespin, 03/16/2020 11:00 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 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
@PATH="$PATH:/foo/bar/libosmocore" make REL=minor release --include-dir="/foo/bar/libosmocore"@
59
60 61 pespin
h3. Dependencies
61 1 neels
62 61 pespin
The @osmo-release.mk@ requires several extra dependencies. Make sure you have them installed in your system:
63
* bumpversion
64
* git-buildpackage
65
* devscripts
66
67
h3. TODO-RELEASE file format and maintenance
68
69
* all the strings which contain @#@ considered comment and will be ignored
70
* actual entries consists of 3 tab-separated fields:
71
# library - name of the library affected (should correspond to @lib*.pc.in@ file in project's root directory)
72
# what - API or ABI change (used as a guidance to properly bump @*_LIBVERSION@)
73
# description - textual description (will end up in changelog)
74
75
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.
76
77
h2. How to make a new release
78
79
First we outline specific steps for different project types, then common part.
80 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@
81 82 pespin
* Adjust dependency versions in @debian/control@ (under @Build-Depends@) to match those of configure.ac
82 84 pespin
* Make sure patches under @debian/patches@ still apply correctly.
83 61 pespin
84
h3. Extra steps for Libraries
85
86 1 neels
Some extra previous steps are required if the project installs a public shared library.
87
88 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/@
89
* if necessary ("@major = current - age@" component of @*LIBVERSION@ was bumped, package name changing as a result) then:
90
** Rename @debian/lib*.install@ to match the name change. See [[Make_a_new_release#Versioning-considerations-for-libraries|Versioning considerations for libraries]].
91
** Adjust package names in @debian/control@ accordingly. Specifically look for "Package" and "Depends" attributes.
92
** 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.
93 32 msuraev
94 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.
95
96 61 pespin
h3. Release steps
97 1 neels
98 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.
99
100 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@
101 83 pespin
* Make sure all the manual changes you want in the release commit are staged (@git add@), (see previous sections about changes needed).
102 78 osmith
* Run @make REL=minor release@
103 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.
104 44 msuraev
* inspect the latest commit which was just created
105 1 neels
* adjust it if necessary and re-sign (see [[Make_a_new_release#How-to-retag-a-new-release|Re-tag new release]])
106 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).
107 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@
108 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
109 64 pespin
110
In case you want to undo the release commit you did locally:
111
* @git tag -d TAG_JUST_CREATED@
112
* @git reset --soft HEAD^@
113
* @git reset HEAD debian/changelog && git checkout debian/changelog@
114
* Do your modifications
115
* Proceed again with the release steps listed above
116 45 msuraev
117
h2. Which new release to make
118
119
Use following guidelines when choosing release type:
120
* major - ?? TBD
121
* minor - ?? TBD
122 43 msuraev
* patch - ?? TBD
123 1 neels
124 43 msuraev
If unsure - ask in corresponding ML.
125
126
h2. Deprecation policy
127
128
Functions/interfaces marked as deprecated for X releases of type Y can be removed in next Z release.
129
130 55 pespin
TBD: what's appropriate value for X? which Y and Z (from major/minor/patch) should we use?
131 43 msuraev
132
h2. How to (re)tag a new release
133
134 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.
135
136 36 msuraev
<pre>
137
git tag -s 0.4.0 -f -m "Release v0.4.0 on 2017-08-25."
138
</pre>
139 30 msuraev
140
This will automatically (re)sign the latest commit. You can specify which commit to sign explicitly.
141 3 neels
142 1 neels
Say, for example, the git hash is @012342abcdefg@ and the next open version is 0.1.3:
143 9 neels
<pre>
144 1 neels
git tag -s 0.1.3 012342abcdefg -m "release 0.1.3"
145
</pre>
146 8 neels
147 1 neels
(If @gpg@ complains, see [[Make a new release#GPG-Have-a-matching-user-id|GPG: Have a matching user id]].)
148 4 neels
149 1 neels
Verify that git picks up the new version tag:
150
<pre>
151
$ git describe
152
0.1.3-3-g1f95179
153
</pre>
154 11 neels
155 42 msuraev
N. B: *For your local build, _nothing will change_ until you delete the @.version@ file and completely rebuild:*
156 1 neels
157
<pre>
158 10 neels
rm .version
159
autoreconf -fi
160 1 neels
./configure
161
make
162
cat .version
163
</pre>
164
165
This should show the same as @git describe@.
166
167
When you're convinced that all is in order, push the new tag:
168
169
<pre>
170
git push origin 0.1.3
171
</pre>
172 14 neels
173 1 neels
If anything went wrong, you can delete the tag (locally) by
174 15 msuraev
<pre>
175 42 msuraev
git tag -d 0.1.3
176
</pre>
177
and, if you've already pushed it, by
178
<pre>
179
git push --delete origin 0.1.3
180
</pre>
181 1 neels
182
h2. GPG: Have a matching user id
183
184
By default, @git tag -s@ takes your author information to lookup the secret GPG key to sign a tag with.
185
If the author+email do not exactly match one of the key's @uid@s, you will get this error:
186
187
<pre>
188
gpg: signing failed: secret key not available
189
</pre>
190
191
Verify: say, your author+email info in your git config says "John Doe <john@doe.net>", try
192
<pre>
193
gpg --list-secret-keys "John Doe <john@doe.net>"
194
</pre>
195
If this fails, GPG won't find the right key automatically.
196
197
Ways to resolve:
198
199
* Use @git tag -u <key-id>@
200
* Edit your secret key to add a uid that matches your author information
201
<pre>
202
gpg --edit-key john@doe.net
203
gpg> adduid
204
# enter details to match the git author
205
gpg> save
206
</pre>
207 56 pespin
208 87 laforge
h1. Creating a patch release
209
210 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:
211 87 laforge
212 88 laforge
# (locally checkout 1.3.0 as a new branch called rel-1.3.1)
213
<pre>
214
git checkout -b rel-1.3.1 1.3.0
215
</pre>
216
# create a rel-1.3.1 branch in gerrit
217
<pre>
218
git push gerrit rel-1.3.1:refs/heads/rel-1.3.1
219
</pre>
220 1 neels
# do whatever local modifications such as cherry-picking of fixes, ...
221 88 laforge
# perform the release process as outlined above, using 'REL=patch'
222
<pre>
223
make REL=patch release
224
</pre>
225
# push the changes for review to the rel-1.3.1 branch
226
<pre>
227
git push gerrit HEAD:refs/for/rel-1.3.1
228
</pre>
229 1 neels
# perform gerrit review, merge patches
230 88 laforge
# push the tag to the repo, *after the patches were merged* to that branch
231
<pre>
232
git push gerrit 1.3.1
233
</pre>
234
# remove the temporary branch
235
<pre>
236
git push gerrit :rel-1.3.1
237
</pre>
238 56 pespin
239
h1. Dependency graph
240
241
This section aims at providing a dependency graph of the osmocom cellular network infrastructure projects in case a cascade of releases is intended:
242 66 pespin
243 56 pespin
{{graphviz_link()
244
digraph G {
245
    libusrp -> {osmo_trx};
246 75 pespin
    libas1nc -> {osmo_iuh, osmo_msc, openbsc};
247 85 pespin
    libsmpp34 -> {osmo_msc, openbsc};
248 60 pespin
    libgtpnl -> {osmo_ggsn};
249 56 pespin
    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, osmo_sip_connector, osmo_pcap};
250
    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};
251 63 pespin
    libosmo_abis -> {libosmo_netif, osmo_sgsn, osmo_msc, osmo_hlr, osmo_bsc, osmo_bts, openbsc};
252 56 pespin
    libosmo_netif -> {libosmo_sccp, osmo_iuh, osmo_sgsn, osmo_mgw, osmo_msc, osmo_bsc, openbsc};
253
    libosmo_sccp -> {osmo_iuh, osmo_sgsn, osmo_msc, osmo_bsc, openbsc};
254 69 pespin
    osmo_iuh -> {osmo_msc, osmo_sgsn, openbsc};
255 56 pespin
    osmo_ggsn -> {osmo_sgsn};
256
    osmo_mgw -> {osmo_msc, osmo_bsc};
257 1 neels
    osmo_hlr -> {osmo_msc, osmo_sgsn};
258
}
259
}}
Add picture from clipboard (Maximum size: 48.8 MB)