ericonr
/
util-linux
mirror of https://github.com/ericonr/util-linux.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: update howto-contribute.txt 

Grammar fixes and some clarification changes.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
This commit is contained in:
J William Piggott 2017-05-28 15:49:09 -04:00
parent ebcb28e53a
commit 888d5e0ed6
1 changed files with 81 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
Documentation/howto-contribute.txt
View File

@ -1,43 +1,50 @@
Patches
* send your patches to the mailing list or to the upstream maintainer
(see the README file in project root directory).
* send your patches to the mailing list or to the project maintainer.
See ../README.
* don't include generated (autotools) stuff to your patches (hint:
use git clean -Xd)
* don't include generated (autotools) files in 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.
* 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.
* 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.
* 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 source-code-management.txt
for git repository instructions.
* one patch per email, with the changelog in the body of the email.
* one patch per email.
See Email Format.
* mail attachments are difficult. Tip:
git send-email --to util-linux@vger.kernel.org origin/master..yourbranch
* email attachments are difficult to review and not recommended.
Hint: use 'git send-email'.
* 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
* 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.
* 'Subject: [PATCH] subsystem: description'. See also 'Patching
process'.
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:
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")
* 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:
simple; if you can certify the following:
By making a contribution to this project, I certify that:
@ -64,92 +71,94 @@ Patches
consistent with this project or the open source license(s)
involved.
then you just add a line saying
Then you just add a line like:
Signed-off-by: Random J Developer <random@developer.example.org>
using your real name (sorry, no pseudonyms or anonymous
contributions.)
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.
Before sending a patch
* make sure that after patching source files will compile without
errors.
* make sure that after applying your patch the file(s) 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.
* 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.
Coding style
* the preferred coding style is based on the linux kernel
Documentation/CodingStyle. For more details see:
* the preferred coding style is based on the linux kernel coding-style.
Available here:
http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/CodingStyle
http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/coding-style.rst
* Use `FIXME:' and a good description if want to inform others
something is not quite right, and you are unwilling to fix the
* 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.
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
* 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.
* 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.
* 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] ...
* When getting comments align the changes with them. Resubmission
without changes is as good as ignoring advice, and is neither
recommended nor polite.
* incorporate reviewer comments in the patches. Resubmitting without
changes 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.
* 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.
* Mark resubmission with [PATCH v2]. Hint:
git format-patch origin/master..yourbranch --subject-prefix='PATCH v2'
* When resubmitting use the email Subject: [PATCH v2] ...
Hint: use the --subject-prefix='PATCH v2' option with 'git format-patch'
* Use of remote repository for resubmission can be good idea.
See also howto-pull-request.txt
* using a git repository for (re)submissions can make life easier.
See howto-pull-request.txt and source-code-management.txt.
* All patch submissions, big or small, are either commented, reject,
or merge. When maintainer rejects a patch (series) it is pointless
to resubmit.
* all patch submissions are either commented, rejected, or accepted.
If the maintainer rejects a patch set it is pointless to resubmit it.
Various notes
* The util-linux does not use kernel headers for file system super
* 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.
* patches relying on kernel features that are not in Linus Torvalds's
tree are not accepted.
* Do not use `else' after non-returning functions. For
example
* 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
Is wrong and should be written:
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.
* 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.
Standards compliancy
Standards compliance
Some of the commands maintained in this package have Open Group
requirements. These commands are;
requirements. These commands are:
cal
col
@ -164,11 +173,10 @@ Standards compliancy
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.
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
@ -177,10 +185,10 @@ Standards compliancy
IRC channel
* We have a new #util-linux IRC channel at freenode.net.
* #util-linux 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.
This channel is for developers and project maintainers. For end users
it is recommended to utilize the distribution's IRC channel or support
forum.