summaryrefslogtreecommitdiffstats
path: root/CONTRIBUTING
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:40:15 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:40:15 +0000
commit399644e47874bff147afb19c89228901ac39340e (patch)
tree1c4c0b733f4c16b5783b41bebb19194a9ef62ad1 /CONTRIBUTING
parentInitial commit. (diff)
downloadmanpages-399644e47874bff147afb19c89228901ac39340e.tar.xz
manpages-399644e47874bff147afb19c89228901ac39340e.zip
Adding upstream version 6.05.01.upstream/6.05.01
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'CONTRIBUTING')
-rw-r--r--CONTRIBUTING228
1 files changed, 228 insertions, 0 deletions
diff --git a/CONTRIBUTING b/CONTRIBUTING
new file mode 100644
index 0000000..b08000b
--- /dev/null
+++ b/CONTRIBUTING
@@ -0,0 +1,228 @@
+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:
+ 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>
+
+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>