summaryrefslogtreecommitdiffstats
path: root/Documentation/howto-contribute.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/howto-contribute.txt')
-rw-r--r--Documentation/howto-contribute.txt248
1 files changed, 248 insertions, 0 deletions
diff --git a/Documentation/howto-contribute.txt b/Documentation/howto-contribute.txt
new file mode 100644
index 0000000..1b78277
--- /dev/null
+++ b/Documentation/howto-contribute.txt
@@ -0,0 +1,248 @@
+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 https://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://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
+