libseccomp/SUBMITTING_PATCHES

   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.