[thirdparty/util-linux.git] / Documentation / howto-contribute.txt

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

	  We use this repository for master and stable branches only.

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

	  We use this repository to backup kernel.org and for pull requests,
	  issues tracking and topic branches. 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   - development for the next release
	  stable/* - stable maintenance releases

	  Github only:

	  next	   - optionally used when master branch is frozen due to -rcN releases
	  topic/*  - long time development

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://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/coding-style.rst

	* 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
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
0928ca2b WP	8	Standards Compliance
0928ca2b WP	9
0928ca2b WP	10	Sending Patches
90a1baf6	11
39d16258 KZ	12	* send your patches to the mailing list (see ../README) or by
39d16258 KZ	13	github.com pull request.
90a1baf6	14
888d5e0e WP	15	* email is accepted as an inline patch with, or without, a git pull
888d5e0e WP	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
80008bca WP	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.
888d5e0e WP	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.
90a1baf6 SK	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.
033b5a52	35	The po/ stuff is maintained on https://translationproject.org/domain/util-linux.html
68d7dc7b KZ	36	and updated always before the next release.
68d7dc7b KZ	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
90a1baf6 SK	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.
888d5e0e WP	115	Hint: use git commit -s
90a1baf6 SK	116
90a1baf6 SK	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
b3d41ca0 WP	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.
b3d41ca0 WP	159
0928ca2b	160	Coding Style
90a1baf6	161
888d5e0e WP	162	* the preferred coding style is based on the linux kernel coding-style.
888d5e0e WP	163	Available here:
90a1baf6	164
033b5a52	165	https://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
888d5e0e WP	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
888d5e0e WP	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
820f4c4a SK	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
033b5a52	247	https://pubs.opengroup.org/onlinepubs/7908799/xcuix.html
820f4c4a	248