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