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