|
|
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.
|
