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