]>
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 | ||
84b27596 KZ |
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 | ||
0928ca2b WP |
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. | |
80008bca | 90 | See howto-pull-request.txt and ../README. |
0928ca2b WP |
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 | ||
888d5e0e WP |
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. | |
90a1baf6 SK |
101 | |
102 | * if someone else wrote the patch, they should be credited (and | |
888d5e0e | 103 | blamed) for it. To communicate this, add a line like: |
90a1baf6 SK |
104 | |
105 | From: John Doe <jdoe@wherever.com> | |
106 | ||
888d5e0e WP |
107 | * add a Signed-off-by line. |
108 | Hint: use git commit -s | |
90a1baf6 SK |
109 | |
110 | The sign-off is a simple line at the end of the explanation for the | |
b3d41ca0 WP |
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 | |
888d5e0e | 113 | simple; if you can certify the following: |
90a1baf6 SK |
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 | ||
888d5e0e | 140 | Then you just add a line like: |
90a1baf6 SK |
141 | |
142 | Signed-off-by: Random J Developer <random@developer.example.org> | |
143 | ||
888d5e0e WP |
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. | |
90a1baf6 | 150 | |
b3d41ca0 WP |
151 | Note: the mailing list will reject certain content. See ../README. |
152 | ||
0928ca2b | 153 | Coding Style |
90a1baf6 | 154 | |
888d5e0e WP |
155 | * the preferred coding style is based on the linux kernel coding-style. |
156 | Available here: | |
90a1baf6 | 157 | |
888d5e0e | 158 | http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/coding-style.rst |
90a1baf6 | 159 | |
888d5e0e WP |
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 | |
347da736 | 162 | issue in the submitted change. |
c0dcd7d0 | 163 | |
888d5e0e WP |
164 | * do not use `else' after non-returning functions. For |
165 | example: | |
0c121348 SK |
166 | |
167 | if (this) | |
168 | err(EXIT_FAIL, "this failed"); | |
169 | else | |
170 | err(EXIT_FAIL, "that failed"); | |
171 | ||
888d5e0e | 172 | Is wrong and should be written: |
0c121348 SK |
173 | |
174 | if (this) | |
175 | err(EXIT_FAIL, "this failed"); | |
176 | err(EXIT_FAIL, "that failed"); | |
177 | ||
888d5e0e WP |
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. | |
28fa2915 | 181 | |
7948117d WP |
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 | ||
0928ca2b WP |
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 | |
820f4c4a SK |
215 | |
216 | Some of the commands maintained in this package have Open Group | |
888d5e0e | 217 | requirements. These commands are: |
820f4c4a SK |
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 | ||
888d5e0e WP |
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. | |
820f4c4a SK |
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 |