Project

General

Profile

Make a new release » History » Version 67

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