]>
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 | |
93 | the variables available at <lib/dist.mk>, and any makefiles | |
94 | included by that one. See the "Versions" section below. | |
8a60be33 | 95 | |
0837f281 | 96 | - Create the tarball: |
8a60be33 | 97 | |
0837f281 | 98 | $ make dist |
8a60be33 | 99 | |
0837f281 AC |
100 | Since it takes a few seconds, you may prefer to run it in |
101 | parallel: | |
8a60be33 | 102 | |
0837f281 | 103 | $ make -j dist |
8a60be33 | 104 | |
0837f281 AC |
105 | Alternatively, you may want to only create a specific kind of |
106 | tarball with one of the following targets: | |
8a60be33 | 107 | |
0837f281 | 108 | $ make dist-tar dist-xz dist-gz |
8a60be33 | 109 | |
0837f281 | 110 | - Sign the tarball: |
8a60be33 | 111 | |
7c90d7d0 | 112 | $ cd .tmp/ |
0837f281 | 113 | $ gpg --detach-sign --armor man-pages-${new}.tar |
8a60be33 | 114 | |
0837f281 | 115 | - Upload the tarball: |
8a60be33 | 116 | |
0837f281 AC |
117 | $ kup put man-pages-${new}.tar.xz man-pages-${new}.tar.asc \ |
118 | /pub/linux/docs/man-pages/ | |
119 | $ cd .. | |
8a60be33 | 120 | |
0837f281 | 121 | (5) LSM |
8a60be33 | 122 | |
0837f281 AC |
123 | Update the <lsm> file. Check old commits, like |
124 | c11cb1ca844d "Ready for 6.01". | |
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 AC |
134 | $ git add lsm |
135 | $ git commit -sm "lsm: Released ${new}" | |
8a60be33 | 136 | |
0837f281 AC |
137 | - Send (email) the lsm file to <lsm@qqx.org> with the subject |
138 | "add". | |
8a60be33 | 139 | |
0837f281 | 140 | (6) Email |
8a60be33 | 141 | |
0837f281 AC |
142 | Send an announce email to linux-man, LKML, libc-alpha, and |
143 | possibly others that might be interested in the release, such as | |
144 | distribution maintainers, or those who have contributed to the | |
145 | release. | |
8a60be33 | 146 | |
0837f281 AC |
147 | The email should contain a mix of the git tag message, the |
148 | contents of Changes, and anything else that might be relevant. | |
149 | Check old emails such as | |
150 | <https://lore.kernel.org/linux-man/4ba6c215-6d28-1769-52d3-04941b962ff3@kernel.org/T/#u>. | |
8a60be33 | 151 | |
0837f281 | 152 | The subject of the email should be "man-pages-${new} released". |
8a60be33 | 153 | |
0837f281 | 154 | (7) Changes.old |
8a60be33 | 155 | |
0837f281 AC |
156 | Move the contents of <Changes> to <Changes.old>, and prepare for |
157 | the next release. | |
8a60be33 | 158 | |
0837f281 | 159 | - Copy contents of <Changes> to <Changes.old>: |
8a60be33 | 160 | |
0837f281 AC |
161 | $ (echo; echo) >> Changes.old |
162 | $ cat Changes >> Changes.old | |
8a60be33 | 163 | |
0837f281 | 164 | - Empty <Changes>: |
8a60be33 | 165 | |
0837f281 | 166 | $ git checkout man-pages-${new}^^ -- Changes |
8a60be33 | 167 | |
0837f281 | 168 | - Commit: |
8a60be33 | 169 | |
0837f281 AC |
170 | $ git add Changes Changes.old |
171 | $ git commit -sm \ | |
172 | "Start of man-pages-NEXT: Move Changes to Changes.old" | |
8a60be33 | 173 | |
0837f281 | 174 | (8) Push |
8a60be33 | 175 | |
0837f281 AC |
176 | You've finished. When you confirm it's good, push to the git |
177 | repository. | |
2788d24f | 178 | |
0837f281 | 179 | - Push: |
2788d24f | 180 | |
0837f281 | 181 | $ git push |
9549e6f7 AC |
182 | $ git push korg man-pages-${new} |
183 | ||
184 | korg is just my name for the remote. | |
02f78bad AC |
185 | |
186 | Files | |
187 | Changes, Changes.old | |
188 | Change log. Includes most relevant changes. | |
189 | ||
190 | Makefile, lib/dist.mk, lib/version.mk | |
191 | Main makefiles used for releasing (however, others may also be used by | |
192 | inclusion). | |
193 | ||
194 | lsm | |
195 | Linux software map. See also <https://lsm.qqx.org/>. | |
196 | ||
7c90d7d0 | 197 | .tmp/man-pages-<version>.tar{,.xz,.gz} |
02f78bad AC |
198 | Generated tarballs. You can generate all with 'make dist', or generate |
199 | only some of them, with 'make dist-tar', 'make dist-xz', or | |
200 | 'make dist-gz'. | |
201 | ||
202 | Versions | |
203 | Use the DISTVERSION variable when running make(1) to specify a version | |
204 | different than the default, which is generated with git-describe(1). | |
205 | This needs to be done from the git repository, and won't work from an | |
206 | extracted tarball. | |
207 | ||
208 | $ make dist-xz DISTVERSION=6.01+43 | |
209 | ||
210 | Caveats | |
211 | The version and date of last modification for each page is hardcoded | |
212 | by the Makefile into the pages when the tarball is generated. This | |
213 | means that it's not possible to generate a valid tarball from another | |
214 | extracted tarball, since the version and date will not be updated. | |
215 | Tarballs need to be created from the git(1) repository. |