]>
Commit | Line | Data |
---|---|---|
c93e2eec AC |
1 | Name |
2 | Contributing - instructions for contributing to the project | |
974845c5 | 3 | |
c93e2eec | 4 | Synopsis |
315cc123 AC |
5 | Mailing list, patches, lint & check, style guide, bug reports, |
6 | and notes | |
974845c5 | 7 | |
c93e2eec AC |
8 | Description |
9 | Mailing list | |
315cc123 AC |
10 | The main discussions regarding development of the project, |
11 | patches, bugs, news, doubts, etc. happen on the mailing list. | |
12 | To send an email to the project, send it to Alejandro and CC the | |
13 | mailing list: | |
0fd4a9ef | 14 | |
c93e2eec | 15 | To: Alejandro Colomar <alx@kernel.org> |
c93e2eec | 16 | Cc: <linux-man@vger.kernel.org> |
0fd4a9ef | 17 | |
315cc123 AC |
18 | Please CC any relevant developers and mailing lists that may know |
19 | about or be interested in the discussion. If your email | |
20 | discusses a feature or change, and you know which developers | |
21 | added the feature or made the change that your email discusses, | |
22 | please CC them on the email; with luck they may review and | |
23 | comment on it. If you don't know who the developers are, you may | |
24 | be able to discover that information from mailing list archives | |
25 | or from git(1) logs or logs in other version control systems. | |
26 | Obviously, if you are the developer of the feature being | |
27 | discussed in a man-pages email, please identify yourself as such. | |
c93e2eec | 28 | Relevant mailing lists may include: |
0fd4a9ef | 29 | |
c93e2eec | 30 | Cc: LKML <linux-kernel@vger.kernel.org> |
ab5a1258 | 31 | Cc: Linux API <linux-api@vger.kernel.org> |
c93e2eec AC |
32 | Cc: Glibc <libc-alpha@sourceware.org> |
33 | ||
315cc123 AC |
34 | For other kernel mailing lists and maintainers, check the |
35 | <MAINTAINERS> file in the Linux kernel repository. | |
c93e2eec AC |
36 | |
37 | Please don't send HTML email; it will be discarded by the list. | |
38 | ||
39 | Archives: | |
40 | <https://lore.kernel.org/linux-man/> | |
41 | <https://marc.info/?l=linux-man> | |
42 | ||
43 | Subscription: | |
b6ddb894 | 44 | It is not necessary to subscribe to the list to send an |
f5166051 AC |
45 | email. For subscribing to the list, or information about |
46 | it, go to | |
47 | <https://subspace.kernel.org/vger.kernel.org.html>. | |
c93e2eec | 48 | |
3c378b9e | 49 | Sign your emails with PGP |
4b7ae5e6 AC |
50 | We encourage that you sign all of your emails sent to the |
51 | mailing list, (especially) including the ones containing | |
3c378b9e AC |
52 | patches, with your PGP key. This helps establish trust between |
53 | you and other contributors of this project, and prevent others | |
54 | impersonating you. If you don't have a key, it's not mandatory | |
55 | to sign your email, but you're encouraged to create and start | |
a457755c AC |
56 | using a PGP key. See also: |
57 | <https://www.gnupg.org/faq/gnupg-faq.html#use_pgpmime> | |
3c378b9e AC |
58 | |
59 | There are many ways you can sign your patches, and it depends on | |
bd7badfd AC |
60 | your preferred tools. You can use neomutt(1) (>= 20240201) as a |
61 | driver for git-send-email(1). In <~/.gitconfig>, add the | |
62 | following section: | |
3c378b9e AC |
63 | |
64 | [sendemail] | |
bd7badfd | 65 | sendmailcmd = neomutt -C -H - && true |
3c378b9e | 66 | |
c93e2eec AC |
67 | Patches |
68 | If you know how to fix a problem in a manual page (if not, see | |
69 | "Reporting bugs" below), then send a patch in an email. | |
70 | ||
315cc123 AC |
71 | - Follow the instructions for sending mail to the mailing list |
72 | above. | |
c93e2eec | 73 | |
315cc123 AC |
74 | - The subject of the email should contain "[patch]" in the |
75 | subject line. | |
c93e2eec | 76 | |
315cc123 AC |
77 | The above is the minimum needed so that someone might respond to |
78 | your patch. If you did that and someone does not respond within | |
79 | a few days, then ping the email thread, "replying to all". Make | |
80 | sure to send it to the maintainers in addition to the mailing | |
81 | list. | |
c93e2eec | 82 | |
315cc123 AC |
83 | To make your patch even more useful, please note the following |
84 | points: | |
c93e2eec | 85 | |
315cc123 AC |
86 | - Write a suitable subject line. Make sure to mention the |
87 | name(s) of the page(s) being patched. Example: | |
c93e2eec AC |
88 | |
89 | [patch] shmop.2: Add "(void *)" cast to RETURN VALUE | |
90 | ||
315cc123 AC |
91 | - Sign your patch with "Signed-off-by:". Read about the |
92 | "Developer's Certificate of Origin" at | |
c93e2eec AC |
93 | <https://www.kernel.org/doc/Documentation/process/submitting-patches.rst>. |
94 | When appropriate, other tags documented in that file, such as | |
315cc123 AC |
95 | "Reported-by:", "Reviewed-by:", "Acked-by:", and |
96 | "Suggested-by:" can be added to the patch. The man-pages | |
97 | project also uses a "Cowritten-by:" tag with the obvious | |
98 | meaning. Example: | |
c93e2eec AC |
99 | |
100 | Signed-off-by: Alejandro Colomar <alx@kernel.org> | |
101 | ||
102 | - Describe how you obtained the information in your patch. For | |
103 | example, was it: | |
104 | ||
315cc123 AC |
105 | - by reading (or writing) the relevant kernel or (g)libc |
106 | source code? Please provide a pointer to the following | |
107 | code. | |
c93e2eec AC |
108 | |
109 | - from a commit message in the kernel or (g)libc source code | |
110 | repository? Please provide a commit ID. | |
111 | ||
315cc123 AC |
112 | - by writing a test program? Send it with the patch, but |
113 | please make sure it's as simple as possible, and provide | |
114 | instructions on how to use it and/or a demo run. | |
c93e2eec | 115 | |
315cc123 AC |
116 | - from a standards document? Please name the standard, and |
117 | quote the relevant text. | |
c93e2eec AC |
118 | |
119 | - from other documentation? Please provide a pointer to that | |
120 | documentation. | |
121 | ||
315cc123 AC |
122 | - from a mailing list or online forum? Please provide a URL |
123 | if possible. | |
c93e2eec | 124 | |
4b1effe9 | 125 | - Send patches in diff -u format in an email patch. You may |
315cc123 AC |
126 | find it useful to employ git-send-email(1) and |
127 | git-format-patch(1). | |
c93e2eec | 128 | |
315cc123 AC |
129 | - Where relevant, include source code comments that cite commit |
130 | hashes for relevant kernel or glibc changes: | |
c93e2eec AC |
131 | |
132 | .\" commit <40-character-git-hash> | |
133 | ||
134 | - For trivial patches, you can use subject tags: | |
135 | ||
136 | - ffix: Formatting fix. | |
137 | - tfix: Typo fix. | |
138 | - wfix: Minor wording fix. | |
315cc123 AC |
139 | - srcfix: Change to manual page source that doesn't affect |
140 | the output. | |
c93e2eec AC |
141 | |
142 | Example: | |
143 | ||
144 | [patch] tcp.7: tfix | |
145 | ||
146 | - Send logically separate patches. For unrelated pages, or for | |
315cc123 AC |
147 | logically-separate issues in the same page, send separate |
148 | emails. | |
c93e2eec | 149 | |
315cc123 AC |
150 | - Make patches against the latest version of the manual page. |
151 | Use git(1) for getting the latest version. | |
0fd4a9ef | 152 | |
aa344d4b | 153 | Lint & check |
315cc123 AC |
154 | If you plan to patch a manual page, consider running the linters |
155 | and checks configured in the build system, to make sure your | |
156 | change doesn't add new warnings. However, you might still get | |
157 | warnings that are not your fault. To minimize that, do the | |
158 | following steps: | |
1b55aca6 | 159 | |
315cc123 AC |
160 | (1) First use make(1)'s -t option, so that make(1) knows that it |
161 | only needs to lint & check again pages that you will touch. | |
1b55aca6 | 162 | |
aa344d4b | 163 | $ make -t lint check >/dev/null |
1b55aca6 | 164 | |
6b388979 | 165 | (2) Run make(1) again, asking it to imagine that the page wou'll |
315cc123 AC |
166 | modify has been touched, to see which warnings you'll still |
167 | see from that page that are not your fault. | |
1b55aca6 | 168 | |
6b388979 | 169 | $ # replace 'man2/membarrier.2' by the page you'll modify |
aa344d4b | 170 | $ make -W man2/membarrier.2 -k lint check |
1b55aca6 | 171 | |
315cc123 AC |
172 | (3) Apply your changes, and then run make(1) again. You can |
173 | ignore warnings that you saw in step (2), but if you see any | |
174 | new ones, please fix them if you know how, or at least note | |
175 | them in your patch email. | |
1b55aca6 | 176 | |
e626e485 | 177 | $ vi man2/membarrier.2 # do your work |
aa344d4b | 178 | $ make -k lint check |
1b55aca6 | 179 | |
315cc123 AC |
180 | See <INSTALL> for a list of dependencies that this feature |
181 | requires. If you can't meet them all, don't worry; it will still | |
182 | run the linters and checks that you have available. | |
1b55aca6 | 183 | |
e2b3164c | 184 | Style guide |
315cc123 AC |
185 | For a description of the preferred layout of manual pages, as |
186 | well as some style guide notes, see: | |
e2b3164c AC |
187 | |
188 | $ man 7 man-pages | |
189 | ||
190 | It will also be interesting to consult groff_man(7) and | |
315cc123 AC |
191 | groff_man_style(7) for understanding and writing good man(7) |
192 | source code. | |
e2b3164c | 193 | |
bf6c4e00 | 194 | Reporting bugs |
315cc123 AC |
195 | Report bugs to the mailing list, following the instructions above |
196 | for sending mails to the list. If you can write a patch (see | |
197 | instructions for sending patches above), it's preferred. | |
c93e2eec | 198 | |
315cc123 AC |
199 | If you're unsure if the bug is in the manual page or in the code |
200 | being documented (kernel, glibc, ...), it's best to send the | |
201 | report to both at the same time, that is, CC all the mailing | |
202 | lists that may be concerned by the report. | |
c93e2eec | 203 | |
315cc123 AC |
204 | Some distributions (for example Debian) apply patches to the |
205 | upstream manual pages. If you suspect the bug is in one of those | |
206 | patches, report it to your distribution maintainer. | |
c93e2eec AC |
207 | |
208 | Send logically separate reports. For unrelated pages, or for | |
209 | logically-separate issues in the same page, send separate emails. | |
210 | ||
315cc123 AC |
211 | There's also a bugzilla, but we don't use it as much as the |
212 | mailing list. | |
c93e2eec AC |
213 | |
214 | Notes | |
bb108fd0 | 215 | External and autogenerated pages |
315cc123 AC |
216 | A few pages come from external sources. Fixes to the pages |
217 | should really go to the upstream source. | |
bb108fd0 | 218 | |
8502eef3 AC |
219 | tzfile(5), tzselect(8), zdump(8), and zic(8) come from the tz |
220 | project <https://www.iana.org/time-zones>. | |
bb108fd0 | 221 | |
315cc123 AC |
222 | bpf-helpers(7) is autogenerated from the Linux kernel sources |
223 | using scripts. See man-pages commits 53666f6c3 and 19c7f7839 for | |
224 | details. | |
c93e2eec AC |
225 | |
226 | Bugs | |
227 | Bugzilla: | |
228 | <https://bugzilla.kernel.org/buglist.cgi?component=man-pages> | |
bf6c4e00 | 229 | |
c93e2eec AC |
230 | See also |
231 | man-pages(7) | |
974845c5 | 232 | |
c93e2eec | 233 | <https://www.kernel.org/doc/man-pages/linux-man-ml.html> |
c93e2eec AC |
234 | <https://www.kernel.org/doc/man-pages/missing_pages.html> |
235 | <https://www.kernel.org/doc/man-pages/code_of_conduct.html> | |
236 | <https://www.kernel.org/doc/Documentation/process/submitting-patches.rst> |