Documentation/howto-contribute.txt

   1 CONTENTS
   2  Sending Patches
   3  Patching Process
   4  Email Format
   5  Coding Style
   6  Options
   7  Various Notes
   8  Standards Compliance
   9
  10 Sending Patches
  11
  12         * send your patches to the mailing list.
  13           See ../README.
  14
  15         * email is accepted as an inline patch with, or without, a git pull
  16           request. Pull request emails need to include the patch set for review
  17           purposes. See howto-pull-request.txt and ../README for git repository
  18           instructions.
  19
  20         * email attachments are difficult to review and not recommended.
  21           Hint: use git send-email.
  22
  23         * one patch per email.
  24           See Email Format.
  25
  26         * many small patches are preferred over a single large patch. Split
  27           patch sets based upon logical functionality. For example: #endif mark
  28           ups, compiler warnings, and exit code fixes should all be individual
  29           small patches.
  30
  31         * don't include generated (autotools) files in your patches.
  32           Hint: use 'git clean -Xd'.
  33
  34         * neutrality: the files in util-linux should be distribution-neutral.
  35           Packages like RPMs, DEBs, and the rest, are not provided. They should
  36           be available from the distribution.
  37
  38 Patching Process
  39
  40         * announce it on the mailing list when you are going to work with some
  41           particular piece of code for a long time. This helps others to avoid
  42           massive merge conflicts. Small or quick work, does not need to be
  43           announced.
  44
  45         * make sure that after applying your patch the file(s) will compile
  46           without errors.
  47
  48         * test that the previously existing program behavior is not altered. If
  49           the patch intentionally alters the behavior explain what changed, and
  50           the reason for it, in the changelog/commit message.
  51
  52         * only submit changes that you believe are ready to merge. To post a
  53           patch for peer review only, state it clearly in the email and use
  54           the Subject: [PATCH RFC] ...
  55
  56         * incorporate reviewer comments in the patches. Resubmitting without
  57           changes is neither recommended nor polite.
  58
  59         * resubmission can be partial or complete. If only a few alterations are
  60           needed then resubmit those particular patches. When comments cause a
  61           greater effect then resubmit the entire patch set.
  62
  63         * When resubmitting use the email Subject: [PATCH v2] ...
  64           Hint: use the --subject-prefix='PATCH v2' option with 'git format-patch'
  65
  66         * using a git repository for (re)submissions can make life easier.
  67           See howto-pull-request.txt and ../README.
  68
  69         * all patch submissions are either commented, rejected, or accepted.
  70           If the maintainer rejects a patch set it is pointless to resubmit it.
  71
  72 Email Format
  73
  74         * Subject: [PATCH] subsystem: description.
  75
  76         * Start the message body with an explanation of the patch, that is, a
  77           changelog/commit entry.
  78
  79         * if someone else wrote the patch, they should be credited (and
  80           blamed) for it. To communicate this, add a line like:
  81
  82           From: John Doe <jdoe@wherever.com>
  83
  84         * add a Signed-off-by line.
  85           Hint: use git commit -s
  86
  87           The sign-off is a simple line at the end of the explanation for the
  88           patch; which certifies that you wrote it or otherwise have the
  89           right to pass it on as an open-source patch. The rules are pretty
  90           simple; if you can certify the following:
  91
  92           By making a contribution to this project, I certify that:
  93
  94            (a) The contribution was created in whole or in part by me and I
  95                have the right to submit it under the open source license
  96                indicated in the file; or
  97
  98            (b) The contribution is based upon previous work that, to the best
  99                of my knowledge, is covered under an appropriate open source
 100                license and I have the right under that license to submit that
 101                work with modifications, whether created in whole or in part
 102                by me, under the same open source license (unless I am
 103                permitted to submit under a different license), as indicated
 104                in the file; or
 105
 106            (c) The contribution was provided directly to me by some other
 107                person who certified (a), (b) or (c) and I have not modified
 108                it.
 109
 110            (d) I understand and agree that this project and the contribution
 111                are public and that a record of the contribution (including
 112                all personal information I submit with it, including my
 113                sign-off) is maintained indefinitely and may be redistributed
 114                consistent with this project or the open source license(s)
 115                involved.
 116
 117           Then you just add a line like:
 118
 119                Signed-off-by: Random J Developer <random@developer.example.org>
 120
 121           Use your real name (sorry, no pseudonyms or anonymous contributions.)
 122
 123         * Next a single line beginning with three hyphen-minus characters (---)
 124           and nothing else.
 125
 126         * Followed by the unified diff patch.
 127
 128         Note: the mailing list will reject certain content. See ../README.
 129
 130 Coding Style
 131
 132         * the preferred coding style is based on the linux kernel coding-style.
 133           Available here:
 134
 135         http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/coding-style.rst
 136
 137         * use 'FIXME:' with a good description, if you want to inform others
 138           that something is not quite right, and you are unwilling to fix the
 139           issue in the submitted change.
 140
 141         * do not use `else' after non-returning functions. For
 142           example:
 143
 144           if (this)
 145                 err(EXIT_FAIL, "this failed");
 146           else
 147                 err(EXIT_FAIL, "that failed");
 148
 149           Is wrong and should be written:
 150
 151           if (this)
 152                 err(EXIT_FAIL, "this failed");
 153           err(EXIT_FAIL, "that failed");
 154
 155         * when you use 'if' short-shorthand make sure it does not wrap into
 156           multiple lines. In case the shorthand does not look good on one line
 157           use the normal "if () else" syntax.
 158
 159 Options
 160
 161         * The rule of thumb for options is that once they exist, you may not
 162           change them, nor change how they work, nor remove them.
 163
 164         * The following options are well-known, and should not be used for any
 165           other purpose:
 166
 167                 -h, --help     display usage and exit
 168                 -V, --version  display version and exit
 169
 170         * Some commands use peculiar options and arguments. These will continue
 171           to be supported, but anything like them will not be accepted as new
 172           additions. A short list of examples:
 173
 174                 Characters other than '-' to start an option. See '+' in 'more'.
 175
 176                 Using a number as an option. See '-<number>' in 'more'.
 177
 178                 Long options that start with a single '-'. See 'setterm'.
 179
 180                 '-?' is not a synonym for '--help', but is an unknown option
 181                 resulting in a suggestion to try --help due to a getopt failure.
 182
 183 Various Notes
 184
 185         * util-linux does not use kernel headers for file system super
 186           blocks structures.
 187
 188         * patches relying on kernel features that are not in Linus Torvalds's
 189           tree are not accepted.
 190
 191 Standards Compliance
 192
 193         Some of the commands maintained in this package have Open Group
 194         requirements. These commands are:
 195
 196                 cal
 197                 col
 198                 ipcrm
 199                 ipcs
 200                 kill
 201                 line
 202                 logger
 203                 mesg
 204                 more
 205                 newgrp
 206                 pg
 207                 renice
 208
 209         If you change these tools please make sure it does not create a conflict
 210         with the latest standard. For example, it is not recommended to add
 211         short command line options before they are part of the standard.
 212         Introducing new long options is acceptable.
 213
 214                 The Single UNIX(TM) Specification, Version 2
 215                 Copyright (C) 1997 The Open Group
 216
 217                 http://pubs.opengroup.org/onlinepubs/7908799/xcuix.html
 218