diff options
Diffstat (limited to '')
| -rw-r--r-- | CONTRIBUTING | 219 | ||||
| -rw-r--r-- | CONTRIBUTING.d/bugs | 28 | ||||
| -rw-r--r-- | CONTRIBUTING.d/external_pages | 17 | ||||
| -rw-r--r-- | CONTRIBUTING.d/lint | 40 | ||||
| -rw-r--r-- | CONTRIBUTING.d/mail | 67 | ||||
| -rw-r--r-- | CONTRIBUTING.d/patches | 94 | ||||
| -rw-r--r-- | CONTRIBUTING.d/style | 21 |
7 files changed, 281 insertions, 205 deletions
diff --git a/CONTRIBUTING b/CONTRIBUTING index b08000b..f6d48e9 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -3,10 +3,9 @@ Name Synopsis Mailing list, patches, lint & check, style guide, bug reports, - and notes + and more. 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 @@ -15,214 +14,24 @@ Description 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: +Files + CONTRIBUTING.d/mail + Instructions for sending emails to the project - Cc: LKML <linux-kernel@vger.kernel.org> - Cc: Linux API <linux-api@vger.kernel.org> - Cc: Glibc <libc-alpha@sourceware.org> + CONTRIBUTING.d/patches + Instructions for contributing patches - For other kernel mailing lists and maintainers, check the - <MAINTAINERS> file in the Linux kernel repository. + CONTRIBUTING.d/bugs + Instructions for reporting bugs - Please don't send HTML email; it will be discarded by the list. + CONTRIBUTING.d/lint + Instructions for linting manual pages - Archives: - <https://lore.kernel.org/linux-man/> - <https://marc.info/?l=linux-man> + CONTRIBUTING.d/external_pages + Pages imported or generated from other projects - Subscription: - Send a message to <majordomo@vger.kernel.org> containing - the following body: - - subscribe linux-man - - Unsubscribing: - - unsubscribe linux-man - - Help: - - help - - 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> + CONTRIBUTING.d/style + Preferred layout of manual pages and style guide notes 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> diff --git a/CONTRIBUTING.d/bugs b/CONTRIBUTING.d/bugs new file mode 100644 index 0000000..4b8cf74 --- /dev/null +++ b/CONTRIBUTING.d/bugs @@ -0,0 +1,28 @@ +Name + Bugs - instructions for reporting bugs + +Description + Report bugs to the mailing list. If you can write a patch, it's + very welcome. + + 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. If you want to track your bug there, feel free to + open a bug report, but expect more attention in the mailing list. + +See also + CONTRIBUTING + CONTRIBUTING.d/* + + <https://bugzilla.kernel.org/buglist.cgi?component=man-pages> diff --git a/CONTRIBUTING.d/external_pages b/CONTRIBUTING.d/external_pages new file mode 100644 index 0000000..63b3e16 --- /dev/null +++ b/CONTRIBUTING.d/external_pages @@ -0,0 +1,17 @@ +Name + External pages - pages imported or generated from other projects + +Description + 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. + +See also + CONTRIBUTING + CONTRIBUTING.d/* diff --git a/CONTRIBUTING.d/lint b/CONTRIBUTING.d/lint new file mode 100644 index 0000000..0a936d9 --- /dev/null +++ b/CONTRIBUTING.d/lint @@ -0,0 +1,40 @@ +Name + Lint - instructions for linting manual pages + +Description + The entire project + To run the linters and checks for the entire project, run + + $ make lint build check; + + This skips tests that are known to fail. To run those too, run + + $ make lint build check SKIP_XFAIL=no; + + A single page + To run those for a single page, you can take advantage of some + make(1) features: + + (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 build check; + + (2) Run make(1) again, asking it to imagine that the page + you're interested in has been touched. + + $ # replace 'man2/membarrier.2' by any page. + $ make -W man2/membarrier.2 -k lint build check; + + Dependencies + 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. + +See also + CONTRIBUTING + CONTRIBUTING.d/* + INSTALL + + $ make help diff --git a/CONTRIBUTING.d/mail b/CONTRIBUTING.d/mail new file mode 100644 index 0000000..48e5b9a --- /dev/null +++ b/CONTRIBUTING.d/mail @@ -0,0 +1,67 @@ +Name + Mail - instructions for sending email to the project + +Description + 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 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 neomutt(1) (>= 20240201) as a + driver for git-send-email(1). In <~/.gitconfig>, add the + following section: + + [sendemail] + sendmailcmd = neomutt -C -H - && true + +See also + CONTRIBUTING + CONTRIBUTING.d/* + + <https://www.kernel.org/doc/man-pages/linux-man-ml.html> + <https://www.kernel.org/doc/man-pages/code_of_conduct.html> diff --git a/CONTRIBUTING.d/patches b/CONTRIBUTING.d/patches new file mode 100644 index 0000000..96550ce --- /dev/null +++ b/CONTRIBUTING.d/patches @@ -0,0 +1,94 @@ +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>. + + - 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. + +See also + CONTRIBUTING + CONTRIBUTING.d/* + + <https://www.kernel.org/doc/Documentation/process/submitting-patches.rst> diff --git a/CONTRIBUTING.d/style b/CONTRIBUTING.d/style new file mode 100644 index 0000000..da34d1b --- /dev/null +++ b/CONTRIBUTING.d/style @@ -0,0 +1,21 @@ +Name + Style - preferred layout of manual pages and style guide notes + +Description + 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. + +See also + CONTRIBUTING + CONTRIBUTING.d/* + + man-pages(7) + groff_man(7) + groff_man_style(7) + groff_char(7) |