CONTRIBUTING

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