]>
Commit | Line | Data |
---|---|---|
0928ca2b WP |
1 | CONTENTS |
2 | Sending Patches | |
3 | Patching Process | |
4 | Email Format | |
5 | Coding Style | |
7948117d | 6 | Options |
0928ca2b WP |
7 | Various Notes |
8 | Standards Compliance | |
0928ca2b WP |
9 | |
10 | Sending Patches | |
90a1baf6 | 11 | |
80008bca | 12 | * send your patches to the mailing list. |
888d5e0e | 13 | See ../README. |
90a1baf6 | 14 | |
888d5e0e WP |
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 | |
80008bca WP |
17 | purposes. See howto-pull-request.txt and ../README for git repository |
18 | instructions. | |
90a1baf6 | 19 | |
0928ca2b WP |
20 | * email attachments are difficult to review and not recommended. |
21 | Hint: use git send-email. | |
22 | ||
888d5e0e WP |
23 | * one patch per email. |
24 | See Email Format. | |
90a1baf6 | 25 | |
888d5e0e WP |
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 | |
90a1baf6 SK |
29 | small patches. |
30 | ||
0928ca2b WP |
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. | |
80008bca | 67 | See howto-pull-request.txt and ../README. |
0928ca2b WP |
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 | ||
888d5e0e WP |
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. | |
90a1baf6 SK |
78 | |
79 | * if someone else wrote the patch, they should be credited (and | |
888d5e0e | 80 | blamed) for it. To communicate this, add a line like: |
90a1baf6 SK |
81 | |
82 | From: John Doe <jdoe@wherever.com> | |
83 | ||
888d5e0e WP |
84 | * add a Signed-off-by line. |
85 | Hint: use git commit -s | |
90a1baf6 SK |
86 | |
87 | The sign-off is a simple line at the end of the explanation for the | |
b3d41ca0 WP |
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 | |
888d5e0e | 90 | simple; if you can certify the following: |
90a1baf6 SK |
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 | ||
888d5e0e | 117 | Then you just add a line like: |
90a1baf6 SK |
118 | |
119 | Signed-off-by: Random J Developer <random@developer.example.org> | |
120 | ||
888d5e0e WP |
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. | |
90a1baf6 | 127 | |
b3d41ca0 WP |
128 | Note: the mailing list will reject certain content. See ../README. |
129 | ||
0928ca2b | 130 | Coding Style |
90a1baf6 | 131 | |
888d5e0e WP |
132 | * the preferred coding style is based on the linux kernel coding-style. |
133 | Available here: | |
90a1baf6 | 134 | |
888d5e0e | 135 | http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/coding-style.rst |
90a1baf6 | 136 | |
888d5e0e WP |
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 | |
347da736 | 139 | issue in the submitted change. |
c0dcd7d0 | 140 | |
888d5e0e WP |
141 | * do not use `else' after non-returning functions. For |
142 | example: | |
0c121348 SK |
143 | |
144 | if (this) | |
145 | err(EXIT_FAIL, "this failed"); | |
146 | else | |
147 | err(EXIT_FAIL, "that failed"); | |
148 | ||
888d5e0e | 149 | Is wrong and should be written: |
0c121348 SK |
150 | |
151 | if (this) | |
152 | err(EXIT_FAIL, "this failed"); | |
153 | err(EXIT_FAIL, "that failed"); | |
154 | ||
888d5e0e WP |
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. | |
28fa2915 | 158 | |
7948117d WP |
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 | ||
0928ca2b WP |
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 | |
820f4c4a SK |
192 | |
193 | Some of the commands maintained in this package have Open Group | |
888d5e0e | 194 | requirements. These commands are: |
820f4c4a SK |
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 | ||
888d5e0e WP |
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. | |
820f4c4a SK |
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 |