| 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. |
| |
| * 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'. |
| |
| * 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. |
| |
| 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: |
| |
| http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/coding-style.rst |
| |
| * 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 |
| |
| http://pubs.opengroup.org/onlinepubs/7908799/xcuix.html |
| |