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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
Name
Contributing - instructions for contributing to the project
Synopsis
Mailing list, patches, lint & check, style guide, bug reports,
and notes
Description
Mailing list
The main discussions regarding development of the project,
patches, bugs, news, doubts, etc. happen on the mailing list.
To send an email to the project, send it to Alejandro and CC the
mailing list:
To: Alejandro Colomar <alx@kernel.org>
Cc: <linux-man@vger.kernel.org>
Please CC any relevant developers and mailing lists that may know
about or be interested in the discussion. If your email
discusses a feature or change, and you know which developers
added the feature or made the change that your email discusses,
please CC them on the email; with luck they may review and
comment on it. If you don't know who the developers are, you may
be able to discover that information from mailing list archives
or from git(1) logs or logs in other version control systems.
Obviously, if you are the developer of the feature being
discussed in a man-pages email, please identify yourself as such.
Relevant mailing lists may include:
Cc: LKML <linux-kernel@vger.kernel.org>
Cc: Linux API <linux-api@vger.kernel.org>
Cc: Glibc <libc-alpha@sourceware.org>
For other kernel mailing lists and maintainers, check the
<MAINTAINERS> file in the Linux kernel repository.
Please don't send HTML email; it will be discarded by the list.
Archives:
<https://lore.kernel.org/linux-man/>
<https://marc.info/?l=linux-man>
Subscription:
It is not necessary to subscribe to the list to send an
email. For subscribing to the list, or information about
it, go to
<https://subspace.kernel.org/vger.kernel.org.html>.
Sign your emails with PGP
We strongly encourage that you sign all of your emails sent to
the mailing list, (especially) including the ones containing
patches, with your PGP key. This helps establish trust between
you and other contributors of this project, and prevent others
impersonating you. If you don't have a key, it's not mandatory
to sign your email, but you're encouraged to create and start
using a PGP key. See also:
<https://www.gnupg.org/faq/gnupg-faq.html#use_pgpmime>
There are many ways you can sign your patches, and it depends on
your preferred tools. You can use git-send-email(1) in
combination with mutt(1). For that, do the following.
In <~/.gitconfig>, add the following section:
[sendemail]
sendmailcmd = mutt -H - && true
And then, patch mutt(1) to enable encryption in batch and mailx
modes, which is disabled in upstream mutt(1). You can find a
patch here:
<https://gitlab.com/muttmua/mutt/-/merge_requests/173>.
Patches
If you know how to fix a problem in a manual page (if not, see
"Reporting bugs" below), then send a patch in an email.
- Follow the instructions for sending mail to the mailing list
above.
- The subject of the email should contain "[patch]" in the
subject line.
The above is the minimum needed so that someone might respond to
your patch. If you did that and someone does not respond within
a few days, then ping the email thread, "replying to all". Make
sure to send it to the maintainers in addition to the mailing
list.
To make your patch even more useful, please note the following
points:
- Write a suitable subject line. Make sure to mention the
name(s) of the page(s) being patched. Example:
[patch] shmop.2: Add "(void *)" cast to RETURN VALUE
- Sign your patch with "Signed-off-by:". Read about the
"Developer's Certificate of Origin" at
<https://www.kernel.org/doc/Documentation/process/submitting-patches.rst>.
When appropriate, other tags documented in that file, such as
"Reported-by:", "Reviewed-by:", "Acked-by:", and
"Suggested-by:" can be added to the patch. The man-pages
project also uses a "Cowritten-by:" tag with the obvious
meaning. Example:
Signed-off-by: Alejandro Colomar <alx@kernel.org>
- Describe how you obtained the information in your patch. For
example, was it:
- by reading (or writing) the relevant kernel or (g)libc
source code? Please provide a pointer to the following
code.
- from a commit message in the kernel or (g)libc source code
repository? Please provide a commit ID.
- by writing a test program? Send it with the patch, but
please make sure it's as simple as possible, and provide
instructions on how to use it and/or a demo run.
- from a standards document? Please name the standard, and
quote the relevant text.
- from other documentation? Please provide a pointer to that
documentation.
- from a mailing list or online forum? Please provide a URL
if possible.
- Send patches in diff -u format, inline inside the email
message. If you're worried about your mailer breaking the
patch, the send it both inline and as an attachment. You may
find it useful to employ git-send-email(1) and
git-format-patch(1).
- Where relevant, include source code comments that cite commit
hashes for relevant kernel or glibc changes:
.\" commit <40-character-git-hash>
- For trivial patches, you can use subject tags:
- ffix: Formatting fix.
- tfix: Typo fix.
- wfix: Minor wording fix.
- srcfix: Change to manual page source that doesn't affect
the output.
Example:
[patch] tcp.7: tfix
- Send logically separate patches. For unrelated pages, or for
logically-separate issues in the same page, send separate
emails.
- Make patches against the latest version of the manual page.
Use git(1) for getting the latest version.
Lint & check
If you plan to patch a manual page, consider running the linters
and checks configured in the build system, to make sure your
change doesn't add new warnings. However, you might still get
warnings that are not your fault. To minimize that, do the
following steps:
(1) First use make(1)'s -t option, so that make(1) knows that it
only needs to lint & check again pages that you will touch.
$ make -t lint check >/dev/null
(2) Run make(1) again, asking it to imagine that the page wou'll
modify has been touched, to see which warnings you'll still
see from that page that are not your fault.
$ # replace 'man2/membarrier.2' by the page you'll modify
$ make -W man2/membarrier.2 -k lint check
(3) Apply your changes, and then run make(1) again. You can
ignore warnings that you saw in step (2), but if you see any
new ones, please fix them if you know how, or at least note
them in your patch email.
$ vi man2/membarrier.2 # do your work
$ make -k lint check
See <INSTALL> for a list of dependencies that this feature
requires. If you can't meet them all, don't worry; it will still
run the linters and checks that you have available.
Style guide
For a description of the preferred layout of manual pages, as
well as some style guide notes, see:
$ man 7 man-pages
It will also be interesting to consult groff_man(7) and
groff_man_style(7) for understanding and writing good man(7)
source code.
Reporting bugs
Report bugs to the mailing list, following the instructions above
for sending mails to the list. If you can write a patch (see
instructions for sending patches above), it's preferred.
If you're unsure if the bug is in the manual page or in the code
being documented (kernel, glibc, ...), it's best to send the
report to both at the same time, that is, CC all the mailing
lists that may be concerned by the report.
Some distributions (for example Debian) apply patches to the
upstream manual pages. If you suspect the bug is in one of those
patches, report it to your distribution maintainer.
Send logically separate reports. For unrelated pages, or for
logically-separate issues in the same page, send separate emails.
There's also a bugzilla, but we don't use it as much as the
mailing list.
Notes
External and autogenerated pages
A few pages come from external sources. Fixes to the pages
should really go to the upstream source.
tzfile(5), tzselect(8), zdump(8), and zic(8) come from the tz
project <https://www.iana.org/time-zones>.
bpf-helpers(7) is autogenerated from the Linux kernel sources
using scripts. See man-pages commits 53666f6c3 and 19c7f7839 for
details.
Bugs
Bugzilla:
<https://bugzilla.kernel.org/buglist.cgi?component=man-pages>
See also
man-pages(7)
<https://www.kernel.org/doc/man-pages/linux-man-ml.html>
<https://www.kernel.org/doc/man-pages/missing_pages.html>
<https://www.kernel.org/doc/man-pages/code_of_conduct.html>
<https://www.kernel.org/doc/Documentation/process/submitting-patches.rst>
|
