Make a new release » History » Version 37
msuraev, 08/28/2017 09:22 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 | *FIXME:* following part is disputable and should be fixed |
12 | 29 | msuraev | |
13 | 16 | msuraev | As soon as a feature is added to one Osmocom project that is needed for another dependent project to compile, we should tag at least a minor-revision bump in the depended-upon project and require it in the depending project's configure.ac. To illustrate, let's look at this example: |
14 | |||
15 | 1 | neels | Among others, @openbsc@ depends on the libraries built from @libosmocore@, for example @libosmogsm@. |
16 | As soon as the @libosmogsm@ library gets a new feature used by @openbsc@, like something was added to |
||
17 | @gsm_utils.h@, we shall |
||
18 | 6 | neels | * tag a release in @libosmocore@; say if the previous version was 0.1.2, make it at least 0.1.3. |
19 | 1 | neels | * and in @openbsc@, require @libosmogsm@ >= 0.1.3 in @configure.ac@ |
20 | 16 | msuraev | |
21 | 28 | msuraev | *Proposed policy:* |
22 | 16 | msuraev | * master branch is expected to depend on latest master branches of depended-upon projects |
23 | 24 | msuraev | * make release of depended-upon projects if necessary before making non-library project release |
24 | * make sure that we have correct version dependencies before making non-library project release |
||
25 | 1 | neels | |
26 | 25 | msuraev | Alternatively/additionally we can make timely releases (once per XX months? before every OsmoDevCon?) of non-library projects (and corresponding depended-upon libraries) 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 |
27 | 20 | msuraev | |
28 | 17 | msuraev | h2. How to make a new release |
29 | |||
30 | 35 | msuraev | First we outline specific steps for different project types, than common part. The release helper (installed by @libosmocore-dev@) available via @make release@ takes care of |
31 | 1 | neels | |
32 | 35 | msuraev | * version bump |
33 | * debian/changelog update |
||
34 | * commit |
||
35 | * sign |
||
36 | * tag |
||
37 | |||
38 | Feel free to send patches implementing further automation as you see fit. |
||
39 | |||
40 | 17 | msuraev | h3. Library release |
41 | 30 | msuraev | |
42 | 1 | neels | * modify @*_LIBVERSION@ in @Makefile.am@ as necessary according to TODO-RELEASE file |
43 | 34 | msuraev | |
44 | 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. |
||
45 | 1 | neels | |
46 | h3. Non-library release |
||
47 | |||
48 | 35 | msuraev | Nothing special is required ATM. |
49 | 1 | neels | |
50 | 30 | msuraev | h3. Common steps |
51 | 1 | neels | |
52 | 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. |
53 | 1 | neels | |
54 | 36 | msuraev | * @make REL=minor release@ |
55 | 30 | msuraev | * inspect the latest commit which was just created |
56 | 32 | msuraev | * adjust it if necessary and re-sign (see [[Make_a_new_release#How-to-retag-a-new-release|Re-tag new release]]) |
57 | 30 | msuraev | * push commit for review using @git review -f@ (see [[Gerrit]] for alternatives) |
58 | * push the release tag by @git push gerrit --tags@ |
||
59 | 37 | msuraev | * consider preparing article for https://osmocom.org/news/ and sending announcement to appropriate ML for major release |
60 | 1 | neels | |
61 | 30 | msuraev | h3. How to (re)tag a new release |
62 | 1 | neels | |
63 | 36 | msuraev | <pre> |
64 | git tag -s 0.4.0 -f -m "Release v0.4.0 on 2017-08-25." |
||
65 | </pre> |
||
66 | 30 | msuraev | |
67 | This will automatically (re)sign the latest commit. You can specify which commit to sign explicitly. |
||
68 | 3 | neels | |
69 | 1 | neels | Say, for example, the git hash is @012342abcdefg@ and the next open version is 0.1.3: |
70 | 9 | neels | <pre> |
71 | 1 | neels | git tag -s 0.1.3 012342abcdefg -m "release 0.1.3" |
72 | </pre> |
||
73 | 8 | neels | |
74 | 1 | neels | (If @gpg@ complains, see [[Make a new release#GPG-Have-a-matching-user-id|GPG: Have a matching user id]].) |
75 | 4 | neels | |
76 | 1 | neels | Verify that git picks up the new version tag: |
77 | <pre> |
||
78 | $ git describe |
||
79 | 0.1.3-3-g1f95179 |
||
80 | </pre> |
||
81 | 11 | neels | |
82 | *For your local build, _nothing will change_ until you delete the @.version@ file |
||
83 | and completely rebuild:* |
||
84 | 1 | neels | |
85 | <pre> |
||
86 | 10 | neels | rm .version |
87 | autoreconf -fi |
||
88 | 1 | neels | ./configure |
89 | make |
||
90 | cat .version |
||
91 | </pre> |
||
92 | |||
93 | This should show the same as @git describe@. |
||
94 | |||
95 | When you're convinced that all is in order, push the new tag: |
||
96 | |||
97 | <pre> |
||
98 | git push origin 0.1.3 |
||
99 | </pre> |
||
100 | 14 | neels | |
101 | 1 | neels | If anything went wrong, you can delete the tag (locally) by |
102 | 15 | msuraev | <pre> |
103 | 14 | neels | git tag -d 0.1.3 |
104 | </pre> |
||
105 | and, if you've already pushed it, by |
||
106 | <pre> |
||
107 | git push --delete origin 0.1.3 |
||
108 | 1 | neels | </pre> |
109 | 26 | msuraev | |
110 | h2. Deprecation policy |
||
111 | 27 | msuraev | |
112 | 26 | msuraev | Functions/interfaces marked as deprecated for X releases of type Y can be removed in next Z release. |
113 | 27 | msuraev | |
114 | 26 | msuraev | TBD: what's appropriate value for X? which Y and Z (from major/minor/patch) should we use? |
115 | 1 | neels | |
116 | h2. GPG: Have a matching user id |
||
117 | |||
118 | By default, @git tag -s@ takes your author information to lookup the secret GPG key to sign a tag with. |
||
119 | If the author+email do not exactly match one of the key's @uid@s, you will get this error: |
||
120 | |||
121 | <pre> |
||
122 | gpg: signing failed: secret key not available |
||
123 | </pre> |
||
124 | |||
125 | Verify: say, your author+email info in your git config says "John Doe <john@doe.net>", try |
||
126 | <pre> |
||
127 | gpg --list-secret-keys "John Doe <john@doe.net>" |
||
128 | </pre> |
||
129 | If this fails, GPG won't find the right key automatically. |
||
130 | |||
131 | Ways to resolve: |
||
132 | |||
133 | * Use @git tag -u <key-id>@ |
||
134 | * Edit your secret key to add a uid that matches your author information |
||
135 | <pre> |
||
136 | gpg --edit-key john@doe.net |
||
137 | gpg> adduid |
||
138 | # enter details to match the git author |
||
139 | gpg> save |
||
140 | </pre> |