]>
Commit | Line | Data |
---|---|---|
8befd5cc MG |
1 | How to Submit Patches to the libseccomp Project |
2 | =============================================================================== | |
3 | https://github.com/seccomp/libseccomp | |
4 | ||
5 | This document is intended to act as a guide to help you contribute to the | |
6 | libseccomp project. It is not perfect, and there will always be exceptions | |
7 | to the rules described here, but by following the instructions below you | |
8 | should have a much easier time getting your work merged with the upstream | |
9 | project. | |
10 | ||
11 | * Test Your Code | |
12 | ||
13 | There are three possible tests you can run to verify your code. The first | |
14 | test is used to check the formatting and coding style of your changes, you | |
15 | can run the test with the following command: | |
16 | ||
17 | # make check-syntax | |
18 | ||
19 | ... if there are any problems with your changes a diff/patch will be shown | |
20 | which indicates the problems and how to fix them. | |
21 | ||
22 | The second possible test is used to ensure that the different internal syscall | |
23 | tables are consistent and to test your changes against the automated test | |
24 | suite. You can run the test with the following command: | |
25 | ||
26 | # make check | |
27 | ||
28 | ... if there are any faults or errors they will be displayed; beware that the | |
29 | tests can run for some time and produce a lot of output. | |
30 | ||
31 | The third possible test is used to validate libseccomp against a live, running | |
32 | system using some simple regression tests. After ensuring that your system | |
33 | supports seccomp filters you can run the live tests with the following | |
34 | command: | |
35 | ||
36 | # make check-build | |
37 | # cd tests | |
38 | # ./regression -T live | |
39 | ||
40 | ... if there are any faults or errors they will be displayed. | |
41 | ||
42 | * Generate the Patch(es) | |
43 | ||
44 | Depending on how you decided to work with the libseccomp code base and what | |
45 | tools you are using there are different ways to generate your patch(es). | |
46 | However, regardless of what tools you use, you should always generate your | |
47 | patches using the "unified" diff/patch format and the patches should always | |
48 | apply to the libseccomp source tree using the following command from the top | |
49 | directory of the libseccomp sources: | |
50 | ||
51 | # patch -p1 < changes.patch | |
52 | ||
53 | If you are not using git, stacked git (stgit), or some other tool which can | |
54 | generate patch files for you automatically, you may find the following command | |
55 | helpful in generating patches, where "libseccomp.orig/" is the unmodified | |
56 | source code directory and "libseccomp/" is the source code directory with your | |
57 | changes: | |
58 | ||
59 | # diff -purN libseccomp.orig/ libseccomp/ | |
60 | ||
61 | When in doubt please generate your patch and try applying it to an unmodified | |
62 | copy of the libseccomp sources; if it fails for you, it will fail for the rest | |
63 | of us. | |
64 | ||
65 | * Explain Your Work | |
66 | ||
67 | At the top of every patch you should include a description of the problem you | |
68 | are trying to solve, how you solved it, and why you chose the solution you | |
69 | implemented. If you are submitting a bug fix, it is also incredibly helpful | |
70 | if you can describe/include a reproducer for the problem in the description as | |
71 | well as instructions on how to test for the bug and verify that it has been | |
72 | fixed. | |
73 | ||
74 | * Sign Your Work | |
75 | ||
76 | The sign-off is a simple line at the end of the patch description, which | |
77 | certifies that you wrote it or otherwise have the right to pass it on as an | |
78 | open-source patch. The "Developer's Certificate of Origin" pledge is taken | |
79 | from the Linux Kernel and the rules are pretty simple: | |
80 | ||
81 | Developer's Certificate of Origin 1.1 | |
82 | ||
83 | By making a contribution to this project, I certify that: | |
84 | ||
85 | (a) The contribution was created in whole or in part by me and I | |
86 | have the right to submit it under the open source license | |
87 | indicated in the file; or | |
88 | ||
89 | (b) The contribution is based upon previous work that, to the best | |
90 | of my knowledge, is covered under an appropriate open source | |
91 | license and I have the right under that license to submit that | |
92 | work with modifications, whether created in whole or in part | |
93 | by me, under the same open source license (unless I am | |
94 | permitted to submit under a different license), as indicated | |
95 | in the file; or | |
96 | ||
97 | (c) The contribution was provided directly to me by some other | |
98 | person who certified (a), (b) or (c) and I have not modified | |
99 | it. | |
100 | ||
101 | (d) I understand and agree that this project and the contribution | |
102 | are public and that a record of the contribution (including all | |
103 | personal information I submit with it, including my sign-off) is | |
104 | maintained indefinitely and may be redistributed consistent with | |
105 | this project or the open source license(s) involved. | |
106 | ||
107 | ... then you just add a line to the bottom of your patch description, with | |
108 | your real name, saying: | |
109 | ||
110 | Signed-off-by: Random J Developer <random@developer.example.org> | |
111 | ||
112 | * Email Your Patch(es) | |
113 | ||
114 | Finally, you will need to email your patches to the mailing list so they can | |
115 | be reviewed and potentially merged into the main libseccomp repository. When | |
116 | sending patches to the mailing list it is important to send your email in text | |
117 | form, no HTML mail please, and ensure that your email client does not mangle | |
118 | your patches. It should be possible to save your raw email to disk and apply | |
119 | it directly to the libseccomp source code; if that fails then you likely have | |
120 | a problem with your email client. When in doubt try a test first by sending | |
121 | yourself an email with your patch and attempting to apply the emailed patch to | |
122 | the libseccomp repository; if it fails for you, it will fail for the rest of | |
123 | us trying to test your patch and include it in the main libseccomp repository. |