]>
Commit | Line | Data |
---|---|---|
0837f281 AC |
1 | Name |
2 | Release - instructions for releasing a new version | |
8a60be33 | 3 | |
0837f281 AC |
4 | Synopsis |
5 | Change log, git tag, tarball, LSM, email, and push. | |
8a60be33 | 6 | |
0837f281 | 7 | Description |
315cc123 AC |
8 | This are the instructions to release a new official version of |
9 | the project. However, these should also be useful for those who | |
10 | simply want to package a random commit (this is done for example | |
11 | by Gentoo). For packaging a random commit without an official | |
12 | release, you only need step (4) "Tarball". | |
8a60be33 | 13 | |
02f78bad | 14 | Dependencies |
315cc123 AC |
15 | The following list of dependencies states what the build system |
16 | (the makefiles) need to perform the relevant (dist) targets: | |
02f78bad | 17 | |
02f78bad | 18 | - echo(1) |
a2cf5189 | 19 | - expr(1) |
02f78bad AC |
20 | - find(1) |
21 | - git(1) | |
22 | - grep(1) | |
23 | - gzip(1) | |
24 | - install(1) | |
25 | - locale(1) | |
26 | - make(1) - GNU Make is required. | |
27 | - sed(1) | |
28 | - sort(1) | |
29 | - tar(1) - GNU tar is required. | |
30 | - xargs(1) | |
31 | - xz(1) | |
32 | ||
315cc123 AC |
33 | Apart from that, the following commands are also needed for other |
34 | tasks shown below: | |
02f78bad AC |
35 | |
36 | - gpg(1) | |
37 | - kup(1) | |
38 | ||
0837f281 AC |
39 | Steps |
40 | (1) Version | |
8a60be33 | 41 | |
0837f281 | 42 | - Decide the version number: |
8a60be33 | 43 | |
0837f281 AC |
44 | $ old=6.01 |
45 | $ new=6.02 | |
8a60be33 | 46 | |
0837f281 | 47 | (2) Changes |
8a60be33 | 48 | |
315cc123 | 49 | Fill the <Changes> file. For that you can check older |
299f7918 AC |
50 | commits: `git log -p --grep 'Changes: Ready for 6'`. It |
51 | needs manual intervention, but in those commit logs you can | |
315cc123 | 52 | check a few commands that will help. |
8a60be33 | 53 | |
0837f281 AC |
54 | - Remember to change the version number, the date, and the |
55 | location. | |
8a60be33 | 56 | |
315cc123 AC |
57 | - Remove any headers not used for a specific release |
58 | (usually happens with "New and changed links"). | |
8a60be33 | 59 | |
0837f281 | 60 | - The structure is a bit freestyle, but keep it organized. |
299f7918 | 61 | Check how previous releases did it. |
8a60be33 | 62 | |
0837f281 | 63 | - Commit: |
8a60be33 | 64 | |
0837f281 | 65 | $ git add Changes |
83f9c049 | 66 | $ git commit -sm "Changes: Ready for $new" |
8a60be33 | 67 | |
0837f281 | 68 | (3) Tag |
8a60be33 | 69 | |
0837f281 | 70 | Create a signed tag. The tag message should note the most |
315cc123 AC |
71 | important changes in the version being released, since it |
72 | will be read by users and packagers. It should include any | |
73 | information that is especially relevant for them. Check old | |
299f7918 AC |
74 | tags: |
75 | `git tag | grep 'man-pages-6' | tac | xargs git show --stat` | |
8a60be33 | 76 | |
0837f281 | 77 | - Tag: |
8a60be33 | 78 | |
83f9c049 | 79 | $ git tag -s man-pages-$new |
8a60be33 | 80 | |
0837f281 | 81 | (4) Tarball |
8a60be33 | 82 | |
0837f281 | 83 | Creating the tarball will embed in the manual pages both the |
315cc123 AC |
84 | version number, and the date of last modification (in the |
85 | git repository, the pages have placeholders for the date and | |
86 | the version). | |
8a60be33 | 87 | |
315cc123 AC |
88 | You need to create a set of tarballs, sign the .tar archive, |
89 | and upload the compressed tarballs to <kernel.org>. | |
8a60be33 | 90 | |
0837f281 | 91 | In case you're creating a tarball for distributing a random |
315cc123 AC |
92 | commit, it might be interesting to tweak a few parameters; |
93 | check the variables available at <share/mk/dist.mk>, and any | |
94 | makefiles included by that one. See the "Versions" section | |
95 | below. | |
8a60be33 | 96 | |
0837f281 | 97 | - Create the tarball: |
8a60be33 | 98 | |
0766cc05 | 99 | $ make -Bj4 dist |
8a60be33 | 100 | |
315cc123 AC |
101 | Alternatively, you may want to only create a specific |
102 | kind of tarball with one of the following targets: | |
8a60be33 | 103 | |
0766cc05 | 104 | $ make -Bj4 dist-tar dist-xz dist-gz |
8a60be33 | 105 | |
0837f281 | 106 | - Sign the tarball: |
8a60be33 | 107 | |
7c90d7d0 | 108 | $ cd .tmp/ |
83f9c049 | 109 | $ gpg --detach-sign --armor man-pages-$new.tar |
8a60be33 | 110 | |
926a7f36 AC |
111 | - Verify the signature: |
112 | ||
83f9c049 | 113 | $ gpg --verify man-pages-$new.tar{.asc,} |
926a7f36 | 114 | |
0837f281 | 115 | - Upload the tarball: |
8a60be33 | 116 | |
83f9c049 | 117 | $ kup put man-pages-$new.tar.{xz,asc} \ |
0837f281 AC |
118 | /pub/linux/docs/man-pages/ |
119 | $ cd .. | |
8a60be33 | 120 | |
0837f281 | 121 | (5) LSM |
8a60be33 | 122 | |
299f7918 AC |
123 | Update the <lsm> file. Check old commits: |
124 | `git log -p -- lsm`. | |
8a60be33 | 125 | |
0837f281 | 126 | - Update the project version number. |
8a60be33 | 127 | |
0837f281 | 128 | - Update the release date. |
8a60be33 | 129 | |
0837f281 | 130 | - Update the tarball name and size. |
8a60be33 | 131 | |
0837f281 | 132 | - Commit: |
8a60be33 | 133 | |
0837f281 | 134 | $ git add lsm |
83f9c049 | 135 | $ git commit -sm "lsm: Released $new" |
8a60be33 | 136 | |
315cc123 AC |
137 | - Send (email) the lsm file to <lsm@qqx.org> with the |
138 | subject "add". | |
8a60be33 | 139 | |
0837f281 | 140 | (6) Email |
8a60be33 | 141 | |
0837f281 | 142 | Send an announce email to linux-man, LKML, libc-alpha, and |
315cc123 AC |
143 | possibly others that might be interested in the release, |
144 | such as distribution maintainers, or those who have | |
145 | contributed to the release. | |
8a60be33 | 146 | |
0837f281 | 147 | The email should contain a mix of the git tag message, the |
315cc123 AC |
148 | contents of Changes, and anything else that might be |
149 | relevant. Check old emails such as | |
0837f281 | 150 | <https://lore.kernel.org/linux-man/4ba6c215-6d28-1769-52d3-04941b962ff3@kernel.org/T/#u>. |
8a60be33 | 151 | |
315cc123 | 152 | The subject of the email should be |
83f9c049 | 153 | "man-pages-$new released". |
8a60be33 | 154 | |
0837f281 | 155 | (7) Changes.old |
8a60be33 | 156 | |
315cc123 AC |
157 | Move the contents of <Changes> to <Changes.old>, and prepare |
158 | for the next release. | |
8a60be33 | 159 | |
0837f281 | 160 | - Copy contents of <Changes> to <Changes.old>: |
8a60be33 | 161 | |
0837f281 AC |
162 | $ (echo; echo) >> Changes.old |
163 | $ cat Changes >> Changes.old | |
8a60be33 | 164 | |
0837f281 | 165 | - Empty <Changes>: |
8a60be33 | 166 | |
83f9c049 | 167 | $ git checkout man-pages-$new^^ -- Changes |
8a60be33 | 168 | |
0837f281 | 169 | - Commit: |
8a60be33 | 170 | |
0837f281 AC |
171 | $ git add Changes Changes.old |
172 | $ git commit -sm \ | |
315cc123 | 173 | "Start of man-pages-NEXT: Move Changes to Changes.old" |
8a60be33 | 174 | |
0837f281 | 175 | (8) Push |
8a60be33 | 176 | |
315cc123 AC |
177 | You've finished. When you confirm it's good, push to the |
178 | git repository. | |
2788d24f | 179 | |
0837f281 | 180 | - Push: |
2788d24f | 181 | |
0837f281 | 182 | $ git push |
83f9c049 | 183 | $ git push korg man-pages-$new |
9549e6f7 AC |
184 | |
185 | korg is just my name for the remote. | |
02f78bad AC |
186 | |
187 | Files | |
188 | Changes, Changes.old | |
189 | Change log. Includes most relevant changes. | |
190 | ||
b60faa4d | 191 | GNUmakefile, share/mk/dist.mk, share/mk/version.mk |
315cc123 AC |
192 | Main makefiles used for releasing (however, others may also be |
193 | used by inclusion). | |
02f78bad AC |
194 | |
195 | lsm | |
196 | Linux software map. See also <https://lsm.qqx.org/>. | |
197 | ||
7c90d7d0 | 198 | .tmp/man-pages-<version>.tar{,.xz,.gz} |
0766cc05 | 199 | Generated tarballs. You can generate all with 'make -B dist', or |
315cc123 AC |
200 | generate only some of them, with 'make -B dist-tar', |
201 | 'make -B dist-xz', or 'make -B dist-gz'. | |
02f78bad AC |
202 | |
203 | Versions | |
315cc123 AC |
204 | Use the DISTVERSION variable when running make(1) to specify a |
205 | version different than the default, which is generated with | |
206 | git-describe(1). This needs to be done from the git repository, | |
207 | and won't work from an extracted tarball. | |
02f78bad | 208 | |
0766cc05 | 209 | $ make -B dist-xz DISTVERSION=6.01+43 |
02f78bad AC |
210 | |
211 | Caveats | |
315cc123 AC |
212 | The version and date of last modification for each page is |
213 | hardcoded by the Makefile into the pages when the tarball is | |
214 | generated. This means that it's not possible to generate a valid | |
215 | tarball from another extracted tarball, since the version and | |
216 | date will not be updated. Tarballs need to be created from the | |
217 | git(1) repository. |