CONTRIBUTING.md

   1 Contributing to Jailhouse
   2 =========================
   3
   4 Contributions to Jailhouse are always welcome. This document explains the
   5 general requirements on contributions and the recommended preparation steps. It
   6 also sketches the typical integration process of patches.
   7
   8
   9 Contribution Checklist
  10 ----------------------
  11
  12 - use git to manage your changes [*recomended*]
  13
  14 - follow Documentation/coding-style.txt coding style [**required**]
  15
  16 - structure patches logically, in small steps [**required**]
  17     - one separable functionality/fix/refactoring = one patch
  18     - do not mix those there in a single patch
  19     - after each patch, the tree still has to build and work, i.e. do not add
  20       even temporary breakages inside a patch series (helps when tracking down
  21       bugs)
  22     - use `git rebase -i` to restructure a patch series
  23
  24 - base patches on top of latest master or - if there are dependencies - on next
  25   (note: next is an integration branch that may change non-linearly)
  26
  27 - test patches sufficiently (obvious, but...) [**required**]
  28     - no regressions are caused in affected code
  29     - seemingly unaffected architectures still build (use Travis CI e.g.)
  30     - static code analyzer finds no new defects (register a github fork with
  31       Travis CI and Coverity for free scanning) [*recommended*]
  32     - the world is still spinning
  33
  34 - add signed-off to all patches [**required**]
  35     - to certify the "Developer's Certificate of Origin" according to "Sign
  36       your work" in https://www.kernel.org/doc/Documentation/SubmittingPatches
  37     - check with your employer when not working on your own!
  38
  39 - post patches to mailing list [**required**]
  40     - use `git format-patch/send-email` if possible
  41     - send patches inline, do not append them
  42     - no HTML emails!
  43     - CC people who you think should look at the patches, e.g.
  44       - affected maintainers (see areas of responsibility below)
  45       - someone who wrote a change that is fixed or reverted by you now
  46       - who commented on related changes in the recent past
  47       - who otherwise has expertise and is interested in the topic
  48     - pull requests on github are only optional
  49
  50 - post follow-up version(s) if feedback requires this
  51
  52 - send reminder if nothing happened after about a week
  53
  54
  55 Contribution Integration Process
  56 --------------------------------
  57
  58 1. patch reviews performed on mailing list
  59     * at least by maintainers, but everyone is invited
  60     * feedback has to consider design, functionality and style
  61     * simpler and clearer code preferred, even if original code works fine
  62
  63 2. accepted patches merged into next branch
  64
  65 3. further testing done by community, including CI build tests and code
  66    analyzer runs
  67
  68 4. if no new problems or discussions showed up, acceptance into master
  69     * grace period for master: about 3 days
  70     * urgent fixes may be applied sooner
  71
  72 github facilities are not used for the review process so that people can follow
  73 all changes and related discussions at a single stop, the mailing list. This
  74 may change in the future if github should improve their email integration.
  75
  76
  77 Areas of responsibility
  78 -----------------------
  79
  80 Jailhouse is rather small. Nevertheless, there are different people involved in
  81 different areas of its code. The following list shall give an overview on who
  82 is working in which area and should be involved when discussing changes:
  83
  84 Jan Kiszka <jan.kiszka@siemens.com>:
  85  - overall Jailhouse maintenance
  86  - committer to official repository
  87
  88 Valentine Sinitsyn <valentine.sinitsyn@gmail.com>:
  89  - AMD64 support
  90
  91 Henning Schild <henning.schild@siemens.com>:
  92  - inter-cell communication
  93  - configuration file generator