diff options
Diffstat (limited to 'Documentation/howto-contribute.txt')
| -rw-r--r-- | Documentation/howto-contribute.txt | 248 |
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 + |