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