diff options
author | Paul Moore <paul@paul-moore.com> | 2017-06-19 16:28:38 -0400 |
---|---|---|
committer | Paul Moore <paul@paul-moore.com> | 2017-06-19 16:28:38 -0400 |
commit | e60ae345507c5e8a41f1b7b4f5a488984567ab60 (patch) | |
tree | 7f1a25d0be788cf19485f91fc799ec8eeb559e59 /CONTRIBUTING.md | |
parent | 7c728944a763adc4f0d216d067a40826c1734ee8 (diff) | |
download | libseccomp-e60ae345507c5e8a41f1b7b4f5a488984567ab60.tar.gz |
doc: rename SUBMITTING_PATCHES to CONTRIBUTING
This is in better keeping with the convention of most Open Source
projects.
Signed-off-by: Paul Moore <paul@paul-moore.com>
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r-- | CONTRIBUTING.md | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b3507fa --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,134 @@ +How to Submit Patches to the libseccomp Project +=============================================================================== +https://github.com/seccomp/libseccomp + +This document is intended to act as a guide to help you contribute to the +libseccomp project. It is not perfect, and there will always be exceptions +to the rules described here, but by following the instructions below you +should have a much easier time getting your work merged with the upstream +project. + +## Test Your Code + +There are three possible tests you can run to verify your code. The first +test is used to check the formatting and coding style of your changes, you +can run the test with the following command: + + # make check-syntax + +... if there are any problems with your changes a diff/patch will be shown +which indicates the problems and how to fix them. + +The second possible test is used to ensure that the different internal syscall +tables are consistent and to test your changes against the automated test +suite. You can run the test with the following command: + + # make check + +... if there are any faults or errors they will be displayed; beware that the +tests can run for some time and produce a lot of output. + +The third possible test is used to validate libseccomp against a live, running +system using some simple regression tests. After ensuring that your system +supports seccomp filters you can run the live tests with the following +command: + + # make check-build + # (cd tests; ./regression -T live) + +... if there are any faults or errors they will be displayed. + +## Make Sure Your Code is Tested + +The libseccomp code includes a fairly extensive test suite and any submissions +which add functionality, or significantly change the existing code, should +include additional tests to verify the proper operation of the proposed +changes. + +Code coverage analysis tools have been integrated into the libseccomp code +base, and can be enabled via the "--enable-code-coverage" configure flag and +the "check-code-coverage" make target. Additional details on generating code +coverage information can be found in the .travis.yml file. + +## Generate the Patch(es) + +Depending on how you decided to work with the libseccomp code base and what +tools you are using there are different ways to generate your patch(es). +However, regardless of what tools you use, you should always generate your +patches using the "unified" diff/patch format and the patches should always +apply to the libseccomp source tree using the following command from the top +directory of the libseccomp sources: + + # patch -p1 < changes.patch + +If you are not using git, stacked git (stgit), or some other tool which can +generate patch files for you automatically, you may find the following command +helpful in generating patches, where "libseccomp.orig/" is the unmodified +source code directory and "libseccomp/" is the source code directory with your +changes: + + # diff -purN libseccomp.orig/ libseccomp/ + +When in doubt please generate your patch and try applying it to an unmodified +copy of the libseccomp sources; if it fails for you, it will fail for the rest +of us. + +## Explain Your Work + +At the top of every patch you should include a description of the problem you +are trying to solve, how you solved it, and why you chose the solution you +implemented. If you are submitting a bug fix, it is also incredibly helpful +if you can describe/include a reproducer for the problem in the description as +well as instructions on how to test for the bug and verify that it has been +fixed. + +## Sign Your Work + +The sign-off is a simple line at the end of the patch description, which +certifies that you wrote it or otherwise have the right to pass it on as an +open-source patch. The "Developer's Certificate of Origin" pledge is taken +from the Linux Kernel and the rules are pretty simple: + + Developer's Certificate of Origin 1.1 + + 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 to the bottom of your patch description, with +your real name, saying: + + Signed-off-by: Random J Developer <random@developer.example.org> + +## Email Your Patch(es) + +Finally, you will need to email your patches to the mailing list so they can +be reviewed and potentially merged into the main libseccomp repository. When +sending patches to the mailing list it is important to send your email in text +form, no HTML mail please, and ensure that your email client does not mangle +your patches. It should be possible to save your raw email to disk and apply +it directly to the libseccomp source code; if that fails then you likely have +a problem with your email client. When in doubt try a test first by sending +yourself an email with your patch and attempting to apply the emailed patch to +the libseccomp repository; if it fails for you, it will fail for the rest of +us trying to test your patch and include it in the main libseccomp repository. |