|
Packit |
56e23f |
How to Submit Patches to the libseccomp Project
|
|
Packit |
56e23f |
===============================================================================
|
|
Packit |
56e23f |
https://github.com/seccomp/libseccomp
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
This document is intended to act as a guide to help you contribute to the
|
|
Packit |
56e23f |
libseccomp project. It is not perfect, and there will always be exceptions
|
|
Packit |
56e23f |
to the rules described here, but by following the instructions below you
|
|
Packit |
56e23f |
should have a much easier time getting your work merged with the upstream
|
|
Packit |
56e23f |
project.
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
## Test Your Code
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
There are three possible tests you can run to verify your code. The first
|
|
Packit |
56e23f |
test is used to check the formatting and coding style of your changes, you
|
|
Packit |
56e23f |
can run the test with the following command:
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
# make check-syntax
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
... if there are any problems with your changes a diff/patch will be shown
|
|
Packit |
56e23f |
which indicates the problems and how to fix them.
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
The second possible test is used to ensure that the different internal syscall
|
|
Packit |
56e23f |
tables are consistent and to test your changes against the automated test
|
|
Packit |
56e23f |
suite. You can run the test with the following command:
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
# make check
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
... if there are any faults or errors they will be displayed; beware that the
|
|
Packit |
56e23f |
tests can run for some time and produce a lot of output.
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
The third possible test is used to validate libseccomp against a live, running
|
|
Packit |
56e23f |
system using some simple regression tests. After ensuring that your system
|
|
Packit |
56e23f |
supports seccomp filters you can run the live tests with the following
|
|
Packit |
56e23f |
command:
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
# make check-build
|
|
Packit |
56e23f |
# (cd tests; ./regression -T live)
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
... if there are any faults or errors they will be displayed.
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
## Make Sure Your Code is Tested
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
The libseccomp code includes a fairly extensive test suite and any submissions
|
|
Packit |
56e23f |
which add functionality, or significantly change the existing code, should
|
|
Packit |
56e23f |
include additional tests to verify the proper operation of the proposed
|
|
Packit |
56e23f |
changes.
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
Code coverage analysis tools have been integrated into the libseccomp code
|
|
Packit |
56e23f |
base, and can be enabled via the "--enable-code-coverage" configure flag and
|
|
Packit |
56e23f |
the "check-code-coverage" make target. Additional details on generating code
|
|
Packit |
56e23f |
coverage information can be found in the .travis.yml file.
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
## Generate the Patch(es)
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
Depending on how you decided to work with the libseccomp code base and what
|
|
Packit |
56e23f |
tools you are using there are different ways to generate your patch(es).
|
|
Packit |
56e23f |
However, regardless of what tools you use, you should always generate your
|
|
Packit |
56e23f |
patches using the "unified" diff/patch format and the patches should always
|
|
Packit |
56e23f |
apply to the libseccomp source tree using the following command from the top
|
|
Packit |
56e23f |
directory of the libseccomp sources:
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
# patch -p1 < changes.patch
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
If you are not using git, stacked git (stgit), or some other tool which can
|
|
Packit |
56e23f |
generate patch files for you automatically, you may find the following command
|
|
Packit |
56e23f |
helpful in generating patches, where "libseccomp.orig/" is the unmodified
|
|
Packit |
56e23f |
source code directory and "libseccomp/" is the source code directory with your
|
|
Packit |
56e23f |
changes:
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
# diff -purN libseccomp.orig/ libseccomp/
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
When in doubt please generate your patch and try applying it to an unmodified
|
|
Packit |
56e23f |
copy of the libseccomp sources; if it fails for you, it will fail for the rest
|
|
Packit |
56e23f |
of us.
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
## Explain Your Work
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
At the top of every patch you should include a description of the problem you
|
|
Packit |
56e23f |
are trying to solve, how you solved it, and why you chose the solution you
|
|
Packit |
56e23f |
implemented. If you are submitting a bug fix, it is also incredibly helpful
|
|
Packit |
56e23f |
if you can describe/include a reproducer for the problem in the description as
|
|
Packit |
56e23f |
well as instructions on how to test for the bug and verify that it has been
|
|
Packit |
56e23f |
fixed.
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
## Sign Your Work
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
The sign-off is a simple line at the end of the patch description, which
|
|
Packit |
56e23f |
certifies that you wrote it or otherwise have the right to pass it on as an
|
|
Packit |
56e23f |
open-source patch. The "Developer's Certificate of Origin" pledge is taken
|
|
Packit |
56e23f |
from the Linux Kernel and the rules are pretty simple:
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
Developer's Certificate of Origin 1.1
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
By making a contribution to this project, I certify that:
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
(a) The contribution was created in whole or in part by me and I
|
|
Packit |
56e23f |
have the right to submit it under the open source license
|
|
Packit |
56e23f |
indicated in the file; or
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
(b) The contribution is based upon previous work that, to the best
|
|
Packit |
56e23f |
of my knowledge, is covered under an appropriate open source
|
|
Packit |
56e23f |
license and I have the right under that license to submit that
|
|
Packit |
56e23f |
work with modifications, whether created in whole or in part
|
|
Packit |
56e23f |
by me, under the same open source license (unless I am
|
|
Packit |
56e23f |
permitted to submit under a different license), as indicated
|
|
Packit |
56e23f |
in the file; or
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
(c) The contribution was provided directly to me by some other
|
|
Packit |
56e23f |
person who certified (a), (b) or (c) and I have not modified
|
|
Packit |
56e23f |
it.
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
(d) I understand and agree that this project and the contribution
|
|
Packit |
56e23f |
are public and that a record of the contribution (including all
|
|
Packit |
56e23f |
personal information I submit with it, including my sign-off) is
|
|
Packit |
56e23f |
maintained indefinitely and may be redistributed consistent with
|
|
Packit |
56e23f |
this project or the open source license(s) involved.
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
... then you just add a line to the bottom of your patch description, with
|
|
Packit |
56e23f |
your real name, saying:
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
Signed-off-by: Random J Developer <random@developer.example.org>
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
## Email Your Patch(es)
|
|
Packit |
56e23f |
|
|
Packit |
56e23f |
Finally, you will need to email your patches to the mailing list so they can
|
|
Packit |
56e23f |
be reviewed and potentially merged into the main libseccomp repository. When
|
|
Packit |
56e23f |
sending patches to the mailing list it is important to send your email in text
|
|
Packit |
56e23f |
form, no HTML mail please, and ensure that your email client does not mangle
|
|
Packit |
56e23f |
your patches. It should be possible to save your raw email to disk and apply
|
|
Packit |
56e23f |
it directly to the libseccomp source code; if that fails then you likely have
|
|
Packit |
56e23f |
a problem with your email client. When in doubt try a test first by sending
|
|
Packit |
56e23f |
yourself an email with your patch and attempting to apply the emailed patch to
|
|
Packit |
56e23f |
the libseccomp repository; if it fails for you, it will fail for the rest of
|
|
Packit |
56e23f |
us trying to test your patch and include it in the main libseccomp repository.
|