Documentation/howto-contribute.txt

Patches

	* send your patches to the mailing list or to the upstream maintainer
	  (see the README file in project root directory).

	* don't include generated (autotools) stuff to your patches (hint:
	  use git clean -Xd)

	* neutrality; The stuff in util-linux should be rather
	  distribution-neutral. No RPMs/DEBs/... are provided - get yours
	  from your distributor.

	* patches are delivered via email or git remote repository only.
	  Downloading them from internet servers is a pain.  See
	  howto-pull-request.txt for remote repository instructions.

	* one patch per email, with the changelog in the body of the email.

	* mail attachments are difficult. Tip:
	  git send-email --to util-linux@vger.kernel.org origin/master..yourbranch

	* many small patches are favoured over one big. Break down is done on
	  basis of logical functionality; for example #endif mark ups,
	  compiler warning and exit codes fixes all should be individual
	  small patches.

	* 'Subject: [PATCH] subsystem: description'. See also 'Patching
	  process'.

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

	  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 a open-source patch. The rules are pretty
	  simple: if you can certify the below:

	  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 saying

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

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

Before sending a patch

	* make sure that after patching source files will compile without
	  errors.

	* test that previously existed program behavior is not
	  unintentionally alterred. If you alter the behavior tell about
	  it in commit message.

Coding style

	* the preferred coding style is based on the linux kernel
	  Documentation/CodingStyle. For more details see:

	  http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/CodingStyle

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

Patching process

	* Tell in mail list when you are going to work with some particular
	  piece of code for long time.  This helps other to avoid massive
	  merge conflicts.  Small or quick work does not need to be
	  announced.

	* Submit only changes that you think are ready to merge.  If you only
	  want change review tell your intention clearly in change cover
	  letter, and/or in each patch subject to review-only.

	* When getting comments align the changes with them.  Resubmission
	  without changes is as good as ignoring advice, and is neither
	  recommended nor polite.

	* Resubmission can be partial or complete.  If only few alterations
	  are needed here and there resubmit particular patches.  When
	  comments cause greater effect resubmit everything again.

	* Mark resubmission with [PATCH v2]. Hint:
	  git format-patch origin/master..yourbranch --subject-prefix='PATCH v2'

	* Use of remote repository for resubmission can be good idea.
	  See also howto-pull-request.txt

	* All patch submissions, big or small, are either commented, reject,
	  or merge.  When maintainer rejects a patch (series) it is pointless
	  to resubmit.

Various notes

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

	* Patches relying on features that are not in Linus' tree
	  are not accepted.

	* 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 wrote

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

	* When you use if shortshort hand make sure it is not wrapped to
	  multiple lines. In case the shorthand does not look good on one
	  line use normal "if () else" syntax.

Standards compliancy

	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 a change does not
	conflict with the latest standard.  For example it is
	recommendable not to add short command line options before they
	are part of standard.  Introducing new long options is
	acceptable.

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

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

IRC channel

	* We have a new #util-linux IRC channel at freenode.net.

	  irc://chat.freenode.net/util-linux

	  the channel is for developers or upstream maintainers.  User
	  support is recommended to go to distribution channels or
	  forums.