]>
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 AC |
49 | Fill the <Changes> file. For that you can check older |
50 | commits, like d4e80a7748 "Changes: Ready for 6.01". It | |
51 | needs manual intervention, but in that commit log you can | |
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. |
315cc123 AC |
61 | man-pages-6.00 was a huge release, so it might help to |
62 | check it: 51228378bec7 "Changes: Ready for 6.00". | |
8a60be33 | 63 | |
0837f281 | 64 | - Commit: |
8a60be33 | 65 | |
0837f281 AC |
66 | $ git add Changes |
67 | $ git commit -sm "Changes: Ready for ${new}" | |
8a60be33 | 68 | |
0837f281 | 69 | (3) Tag |
8a60be33 | 70 | |
0837f281 | 71 | Create a signed tag. The tag message should note the most |
315cc123 AC |
72 | important changes in the version being released, since it |
73 | will be read by users and packagers. It should include any | |
74 | information that is especially relevant for them. Check old | |
75 | tags such as 'man-pages-6.00' or 'man-pages-6.01'. | |
8a60be33 | 76 | |
0837f281 | 77 | - Tag: |
8a60be33 | 78 | |
0837f281 | 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/ |
0837f281 | 109 | $ gpg --detach-sign --armor man-pages-${new}.tar |
8a60be33 | 110 | |
0837f281 | 111 | - Upload the tarball: |
8a60be33 | 112 | |
0837f281 AC |
113 | $ kup put man-pages-${new}.tar.xz man-pages-${new}.tar.asc \ |
114 | /pub/linux/docs/man-pages/ | |
115 | $ cd .. | |
8a60be33 | 116 | |
0837f281 | 117 | (5) LSM |
8a60be33 | 118 | |
0837f281 AC |
119 | Update the <lsm> file. Check old commits, like |
120 | c11cb1ca844d "Ready for 6.01". | |
8a60be33 | 121 | |
0837f281 | 122 | - Update the project version number. |
8a60be33 | 123 | |
0837f281 | 124 | - Update the release date. |
8a60be33 | 125 | |
0837f281 | 126 | - Update the tarball name and size. |
8a60be33 | 127 | |
0837f281 | 128 | - Commit: |
8a60be33 | 129 | |
0837f281 AC |
130 | $ git add lsm |
131 | $ git commit -sm "lsm: Released ${new}" | |
8a60be33 | 132 | |
315cc123 AC |
133 | - Send (email) the lsm file to <lsm@qqx.org> with the |
134 | subject "add". | |
8a60be33 | 135 | |
0837f281 | 136 | (6) Email |
8a60be33 | 137 | |
0837f281 | 138 | Send an announce email to linux-man, LKML, libc-alpha, and |
315cc123 AC |
139 | possibly others that might be interested in the release, |
140 | such as distribution maintainers, or those who have | |
141 | contributed to the release. | |
8a60be33 | 142 | |
0837f281 | 143 | The email should contain a mix of the git tag message, the |
315cc123 AC |
144 | contents of Changes, and anything else that might be |
145 | relevant. Check old emails such as | |
0837f281 | 146 | <https://lore.kernel.org/linux-man/4ba6c215-6d28-1769-52d3-04941b962ff3@kernel.org/T/#u>. |
8a60be33 | 147 | |
315cc123 AC |
148 | The subject of the email should be |
149 | "man-pages-${new} released". | |
8a60be33 | 150 | |
0837f281 | 151 | (7) Changes.old |
8a60be33 | 152 | |
315cc123 AC |
153 | Move the contents of <Changes> to <Changes.old>, and prepare |
154 | for the next release. | |
8a60be33 | 155 | |
0837f281 | 156 | - Copy contents of <Changes> to <Changes.old>: |
8a60be33 | 157 | |
0837f281 AC |
158 | $ (echo; echo) >> Changes.old |
159 | $ cat Changes >> Changes.old | |
8a60be33 | 160 | |
0837f281 | 161 | - Empty <Changes>: |
8a60be33 | 162 | |
0837f281 | 163 | $ git checkout man-pages-${new}^^ -- Changes |
8a60be33 | 164 | |
0837f281 | 165 | - Commit: |
8a60be33 | 166 | |
0837f281 AC |
167 | $ git add Changes Changes.old |
168 | $ git commit -sm \ | |
315cc123 | 169 | "Start of man-pages-NEXT: Move Changes to Changes.old" |
8a60be33 | 170 | |
0837f281 | 171 | (8) Push |
8a60be33 | 172 | |
315cc123 AC |
173 | You've finished. When you confirm it's good, push to the |
174 | git repository. | |
2788d24f | 175 | |
0837f281 | 176 | - Push: |
2788d24f | 177 | |
0837f281 | 178 | $ git push |
9549e6f7 AC |
179 | $ git push korg man-pages-${new} |
180 | ||
181 | korg is just my name for the remote. | |
02f78bad AC |
182 | |
183 | Files | |
184 | Changes, Changes.old | |
185 | Change log. Includes most relevant changes. | |
186 | ||
edaa12e6 | 187 | Makefile, share/mk/dist.mk, share/mk/version.mk |
315cc123 AC |
188 | Main makefiles used for releasing (however, others may also be |
189 | used by inclusion). | |
02f78bad AC |
190 | |
191 | lsm | |
192 | Linux software map. See also <https://lsm.qqx.org/>. | |
193 | ||
7c90d7d0 | 194 | .tmp/man-pages-<version>.tar{,.xz,.gz} |
0766cc05 | 195 | Generated tarballs. You can generate all with 'make -B dist', or |
315cc123 AC |
196 | generate only some of them, with 'make -B dist-tar', |
197 | 'make -B dist-xz', or 'make -B dist-gz'. | |
02f78bad AC |
198 | |
199 | Versions | |
315cc123 AC |
200 | Use the DISTVERSION variable when running make(1) to specify a |
201 | version different than the default, which is generated with | |
202 | git-describe(1). This needs to be done from the git repository, | |
203 | and won't work from an extracted tarball. | |
02f78bad | 204 | |
0766cc05 | 205 | $ make -B dist-xz DISTVERSION=6.01+43 |
02f78bad AC |
206 | |
207 | Caveats | |
315cc123 AC |
208 | The version and date of last modification for each page is |
209 | hardcoded by the Makefile into the pages when the tarball is | |
210 | generated. This means that it's not possible to generate a valid | |
211 | tarball from another extracted tarball, since the version and | |
212 | date will not be updated. Tarballs need to be created from the | |
213 | git(1) repository. |