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
|
Name
Patches - instructions for contributing patches
Description
If you know how to fix a problem in a manual page (if not, see
<CONTRIBUTING.d/bugs>), then send a patch in an email.
- Follow the instructions for sending mail to the mailing list
from <CONTRIBUTING.d/mail>. See also "Send the patches"
below.
- 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 in an email patch. 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.
Prepare the patches for email submission
We recommend using git-format-patch(1) to prepare the patches.
Please use --range-diff to document the differences between
revisions of the patch set, even in the first revision.
To prepare a branch to be sent as a patch set (v1):
$ git format-patch -o ./patches master..HEAD \
--range-diff=master -v1 --cover-letter;
The range diff will be included in the cover letter (or in a
single patch, if there is only one):
$ tail -n7 ./patches/v1-0000-cover-letter.patch;
Range-diff against v0:
-: --------- > 1: 7ec952012 foo.3: tfix
-: --------- > 2: d80376b08 bar.3: ffix
-: --------- > 3: 892a12470 foo.3: wfix
--
2.43.0
To send a v2 after some feedback:
$ git format-patch -o ./patches master..HEAD \
--range-diff=old_master..old_HEAD -v2 --cover-letter;
The values for 'old_master' and 'old_HEAD' can be consulted in
the previous cover letter. In this example, it would be
'--range-diff=7ec952012^..892a12470'.
Send the patches
We recommend using git-send-email(1) to send the patches to the
mailing list. For instructions on how to configure and use it,
see <https://git-send-email.io/>. It can also be configured to
use mutt(1) as a driver, which only requires the following
section in <~/.gitconfig> (assuming mutt(1) is already configured
for sending mail):
[sendemail]
sendmailcmd = mutt -H - && true
In <man-pages/.git/config>, the following configuration will
simplify sending to the right addresses:
[sendemail]
to = Alejandro Colomar <alx@kernel.org>
cc = linux-man@vger.kernel.org
Sign the patches with PGP
See <CONTRIBUTING.d/mail> for more details on signing your mail
to the list. git-send-email(1) can be configured to use a recent
version of neomutt(1) (>= 20240201), to sign patches with PGP
(assuming neomutt(1) is already configured for sending signed
mail). neomutt(1)'s -C flag enables crypto:
[sendemail]
sendmailcmd = neomutt -C -H - && true
See also
CONTRIBUTING
CONTRIBUTING.d/*
<https://www.kernel.org/doc/Documentation/process/submitting-patches.rst>
<https://inbox.sourceware.org/gcc/ZiV5unTogyI7rPJA@debian/>
<https://git-send-email.io/>
<https://neomutt.org/feature/cli-crypto>
|
