diff options
Diffstat (limited to 'CONTRIBUTING.d')
| -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 |
6 files changed, 267 insertions, 0 deletions
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) |