CONTRIBUTING

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