]>
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 | |
39d16258 KZ |
12 | * send your patches to the mailing list (see ../README) or by |
13 | github.com pull request. | |
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 | ||
0e85613e | 34 | * don't include po/ (translations) changes to the upstream patches. |
68d7dc7b KZ |
35 | The po/ stuff is maintained on http://translationproject.org/domain/util-linux.html |
36 | and updated always before the next release. | |
37 | ||
0928ca2b WP |
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 | ||
84b27596 KZ |
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: | |
cd252c66 | 50 | git clone git://github.com/util-linux/util-linux.git |
84b27596 KZ |
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 | ||
d454da17 KZ |
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 | |
84b27596 | 67 | |
0928ca2b WP |
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. | |
80008bca | 97 | See howto-pull-request.txt and ../README. |
0928ca2b WP |
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 | ||
888d5e0e WP |
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. | |
90a1baf6 SK |
108 | |
109 | * if someone else wrote the patch, they should be credited (and | |
888d5e0e | 110 | blamed) for it. To communicate this, add a line like: |
90a1baf6 SK |
111 | |
112 | From: John Doe <jdoe@wherever.com> | |
113 | ||
888d5e0e WP |
114 | * add a Signed-off-by line. |
115 | Hint: use git commit -s | |
90a1baf6 SK |
116 | |
117 | The sign-off is a simple line at the end of the explanation for the | |
b3d41ca0 WP |
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 | |
888d5e0e | 120 | simple; if you can certify the following: |
90a1baf6 SK |
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 | ||
888d5e0e | 147 | Then you just add a line like: |
90a1baf6 SK |
148 | |
149 | Signed-off-by: Random J Developer <random@developer.example.org> | |
150 | ||
888d5e0e WP |
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. | |
90a1baf6 | 157 | |
b3d41ca0 WP |
158 | Note: the mailing list will reject certain content. See ../README. |
159 | ||
0928ca2b | 160 | Coding Style |
90a1baf6 | 161 | |
888d5e0e WP |
162 | * the preferred coding style is based on the linux kernel coding-style. |
163 | Available here: | |
90a1baf6 | 164 | |
888d5e0e | 165 | http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/coding-style.rst |
90a1baf6 | 166 | |
888d5e0e WP |
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 | |
347da736 | 169 | issue in the submitted change. |
c0dcd7d0 | 170 | |
888d5e0e WP |
171 | * do not use `else' after non-returning functions. For |
172 | example: | |
0c121348 SK |
173 | |
174 | if (this) | |
175 | err(EXIT_FAIL, "this failed"); | |
176 | else | |
177 | err(EXIT_FAIL, "that failed"); | |
178 | ||
888d5e0e | 179 | Is wrong and should be written: |
0c121348 SK |
180 | |
181 | if (this) | |
182 | err(EXIT_FAIL, "this failed"); | |
183 | err(EXIT_FAIL, "that failed"); | |
184 | ||
888d5e0e WP |
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. | |
28fa2915 | 188 | |
7948117d WP |
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 | ||
0928ca2b WP |
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 | |
820f4c4a SK |
222 | |
223 | Some of the commands maintained in this package have Open Group | |
888d5e0e | 224 | requirements. These commands are: |
820f4c4a SK |
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 | ||
888d5e0e WP |
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. | |
820f4c4a SK |
243 | |
244 | The Single UNIX(TM) Specification, Version 2 | |
245 | Copyright (C) 1997 The Open Group | |
246 | ||
247 | http://pubs.opengroup.org/onlinepubs/7908799/xcuix.html | |
248 |