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