12 * send your patches to the mailing list.
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
20 * email attachments are difficult to review and not recommended.
21 Hint: use git send-email.
23 * one patch per email.
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
31 * don't include generated (autotools) files in your patches.
32 Hint: use 'git clean -Xd'.
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.
38 Repositories & Branches
40 * Primary repository is on kernel.org:
41 git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
43 We use this repository for master and stable branches only.
45 * Backup repository at github.com:
46 git clone git://github.com/karelzak/util-linux.git
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.
52 It's recommended to use github.com for development.
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
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
68 * make sure that after applying your patch the file(s) will compile
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.
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] ...
79 * incorporate reviewer comments in the patches. Resubmitting without
80 changes is neither recommended nor polite.
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.
86 * When resubmitting use the email Subject: [PATCH v2] ...
87 Hint: use the --subject-prefix='PATCH v2' option with 'git format-patch'
89 * using a git repository for (re)submissions can make life easier.
90 See howto-pull-request.txt and ../README.
92 * all patch submissions are either commented, rejected, or accepted.
93 If the maintainer rejects a patch set it is pointless to resubmit it.
97 * Subject: [PATCH] subsystem: description.
99 * Start the message body with an explanation of the patch, that is, a
100 changelog/commit entry.
102 * if someone else wrote the patch, they should be credited (and
103 blamed) for it. To communicate this, add a line like:
105 From: John Doe <jdoe@wherever.com>
107 * add a Signed-off-by line.
108 Hint: use git commit -s
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:
115 By making a contribution to this project, I certify that:
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
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
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
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)
140 Then you just add a line like:
142 Signed-off-by: Random J Developer <random@developer.example.org>
144 Use your real name (sorry, no pseudonyms or anonymous contributions.)
146 * Next a single line beginning with three hyphen-minus characters (---)
149 * Followed by the unified diff patch.
151 Note: the mailing list will reject certain content. See ../README.
155 * the preferred coding style is based on the linux kernel coding-style.
158 http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/coding-style.rst
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.
164 * do not use `else' after non-returning functions. For
168 err(EXIT_FAIL, "this failed");
170 err(EXIT_FAIL, "that failed");
172 Is wrong and should be written:
175 err(EXIT_FAIL, "this failed");
176 err(EXIT_FAIL, "that failed");
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.
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.
187 * The following options are well-known, and should not be used for any
190 -h, --help display usage and exit
191 -V, --version display version and exit
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:
197 Characters other than '-' to start an option. See '+' in 'more'.
199 Using a number as an option. See '-<number>' in 'more'.
201 Long options that start with a single '-'. See 'setterm'.
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.
208 * util-linux does not use kernel headers for file system super
211 * patches relying on kernel features that are not in Linus Torvalds's
212 tree are not accepted.
216 Some of the commands maintained in this package have Open Group
217 requirements. These commands are:
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.
237 The Single UNIX(TM) Specification, Version 2
238 Copyright (C) 1997 The Open Group
240 http://pubs.opengroup.org/onlinepubs/7908799/xcuix.html