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