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