summaryrefslogtreecommitdiffstats
path: root/Documentation/howto-contribute.txt
blob: 97f3ce1e1600b08fccb686eeaf14d1ca73bf502d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
CONTENTS
 Sending Patches
 Patching Process
 Email Format
 Coding Style
 Options
 Various Notes
 Standards Compliance

Sending Patches

	* send your patches to the mailing list (see ../README) or by
	  github.com pull request.

	* email is accepted as an inline patch with, or without, a git pull
	  request. Pull request emails need to include the patch set for review
	  purposes. See howto-pull-request.txt and ../README for git repository
	  instructions.

	* email attachments are difficult to review and not recommended.
	  Hint: use git send-email.

	* one patch per email.
	  See Email Format.

	* many small patches are preferred over a single large patch. Split
	  patch sets based upon logical functionality. For example: #endif mark
	  ups, compiler warnings, and exit code fixes should all be individual
	  small patches.

	* don't include generated (autotools) files in your patches.
	  Hint: use 'git clean -Xd'.

        * don't include po/ (translations) changes to the upstream patches.
          The po/ stuff is maintained on https://translationproject.org/domain/util-linux.html
          and updated always before the next release.

	* neutrality: the files in util-linux should be distribution-neutral.
	  Packages like RPMs, DEBs, and the rest, are not provided. They should
	  be available from the distribution.

Repositories & Branches

	* Primary repository is on kernel.org:
          git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git

	* Backup repository at github.com:
	  git clone https://github.com/util-linux/util-linux.git

	  We use this repository to backup kernel.org and for PULL REQUESTS,
	  issues tracking. The master and stable branches are always pushed to
	  the both repositories in the same time.

	  It's recommended to use github.com for development.

	* Branches:

	  master      - continuous development
	  stable/vX.Y - stable releases

	  Since version 2.40, the "master" branch remains continuously open and is 
	  never subjected to feature freezes. The stabilization process for
	  the upcoming release is exclusively conducted within the "stable/" branches.
	  Upon branching from "master" to "stable/vX.Y," a new tag vX.Y+1-devel
	  is generated to serve as placeholder for git-based versioning (refer to
	  tools/git-version-gen). Subsequently, changes specific to the new release
	  (such as po/ updates) are selectively cherry-picked from "stable/vX.Y" to
	  "master" after the final release.

Patching Process

	* announce it on the mailing list when you are going to work with some
	  particular piece of code for a long time. This helps others to avoid
	  massive merge conflicts. Small or quick work, does not need to be
	  announced.

	* make sure that after applying your patch the file(s) will compile
	  without errors.

	* test that the previously existing program behavior is not altered. If
	  the patch intentionally alters the behavior explain what changed, and
	  the reason for it, in the changelog/commit message.

	* only submit changes that you believe are ready to merge. To post a
	  patch for peer review only, state it clearly in the email and use
	  the Subject: [PATCH RFC] ...

	* incorporate reviewer comments in the patches. Resubmitting without
	  changes is neither recommended nor polite.

	* resubmission can be partial or complete. If only a few alterations are
	  needed then resubmit those particular patches. When comments cause a
	  greater effect then resubmit the entire patch set.

	* When resubmitting use the email Subject: [PATCH v2] ...
	  Hint: use the --subject-prefix='PATCH v2' option with 'git format-patch'

	* using a git repository for (re)submissions can make life easier.
	  See howto-pull-request.txt and ../README.

	* all patch submissions are either commented, rejected, or accepted.
	  If the maintainer rejects a patch set it is pointless to resubmit it.

Email Format

	* Subject: [PATCH] subsystem: description.

	* Start the message body with an explanation of the patch, that is, a
	  changelog/commit entry.

	* if someone else wrote the patch, they should be credited (and
	  blamed) for it. To communicate this, add a line like:

	  From: John Doe <jdoe@wherever.com>

	* add a Signed-off-by line.
	  Hint: use git commit -s

	  The sign-off is a simple line at the end of the explanation for the
	  patch; which certifies that you wrote it or otherwise have the
	  right to pass it on as an open-source patch. The rules are pretty
	  simple; if you can certify the following:

	  By making a contribution to this project, I certify that:

	   (a) The contribution was created in whole or in part by me and I
	       have the right to submit it under the open source license
	       indicated in the file; or

	   (b) The contribution is based upon previous work that, to the best
	       of my knowledge, is covered under an appropriate open source
	       license and I have the right under that license to submit that
	       work with modifications, whether created in whole or in part
	       by me, under the same open source license (unless I am
	       permitted to submit under a different license), as indicated
	       in the file; or

	   (c) The contribution was provided directly to me by some other
	       person who certified (a), (b) or (c) and I have not modified
	       it.

	   (d) I understand and agree that this project and the contribution
	       are public and that a record of the contribution (including
	       all personal information I submit with it, including my
	       sign-off) is maintained indefinitely and may be redistributed
	       consistent with this project or the open source license(s)
	       involved.

	  Then you just add a line like:

	       Signed-off-by: Random J Developer <random@developer.example.org>

	  Use your real name (sorry, no pseudonyms or anonymous contributions.)

	* Next a single line beginning with three hyphen-minus characters (---)
	  and nothing else.

	* Followed by the unified diff patch.

	Note: the mailing list will reject certain content. See ../README.

Coding Style

	* the preferred coding style is based on the linux kernel coding-style.
	  Available here:

	https://docs.kernel.org/process/coding-style.html

	* use 'FIXME:' with a good description, if you want to inform others
	  that something is not quite right, and you are unwilling to fix the
	  issue in the submitted change.

	* do not use `else' after non-returning functions. For
	  example:

	  if (this)
		err(EXIT_FAIL, "this failed");
	  else
		err(EXIT_FAIL, "that failed");

	  Is wrong and should be written:

	  if (this)
		err(EXIT_FAIL, "this failed");
	  err(EXIT_FAIL, "that failed");

	* when you use 'if' short-shorthand make sure it does not wrap into
	  multiple lines. In case the shorthand does not look good on one line
	  use the normal "if () else" syntax.

Options

	* The rule of thumb for options is that once they exist, you may not
	  change them, nor change how they work, nor remove them.

	* The following options are well-known, and should not be used for any
	  other purpose:

		-h, --help     display usage and exit
		-V, --version  display version and exit

	* Some commands use peculiar options and arguments. These will continue
	  to be supported, but anything like them will not be accepted as new
	  additions. A short list of examples:

		Characters other than '-' to start an option. See '+' in 'more'.

		Using a number as an option. See '-<number>' in 'more'.

		Long options that start with a single '-'. See 'setterm'.

		'-?' is not a synonym for '--help', but is an unknown option
		resulting in a suggestion to try --help due to a getopt failure.

Various Notes

	* util-linux does not use kernel headers for file system super
	  blocks structures.

	* patches relying on kernel features that are not in Linus Torvalds's
	  tree are not accepted.

Standards Compliance

	Some of the commands maintained in this package have Open Group
	requirements. These commands are:

		cal
		col
		ipcrm
		ipcs
		kill
		line
		logger
		mesg
		more
		newgrp
		pg
		renice

	If you change these tools please make sure it does not create a conflict
	with the latest standard. For example, it is not recommended to add
	short command line options before they are part of the standard.
	Introducing new long options is acceptable.

		The Single UNIX(TM) Specification, Version 2
		Copyright (C) 1997 The Open Group

		https://pubs.opengroup.org/onlinepubs/7908799/xcuix.html