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     - the world is still spinning
  31
  32 - add signed-off to all patches [**required**]
  33     - to certify the "Developer's Certificate of Origin" according to "Sign
  34       your work" in https://www.kernel.org/doc/Documentation/SubmittingPatches
  35     - check with your employer when not working on your own!
  36
  37 - post patches to mailing list [**required**]
  38     - use `git format-patch/send-email` if possible
  39     - send patches inline, do not append them
  40     - no HTML emails!
  41     - CC people who you think should look at the patches, e.g.
  42       - affected maintainers (see areas of responsibility below)
  43       - someone who wrote a change that is fixed or reverted by you now
  44       - who commented on related changes in the recent past
  45       - who otherwise has expertise and is interested in the topic
  46     - pull requests on github are only optional
  47
  48 - post follow-up version(s) if feedback requires this
  49
  50 - send reminder if nothing happened after about a week
  51
  52
  53 Contribution Integration Process
  54 --------------------------------
  55
  56 1. patch reviews performed on mailing list
  57     * at least by maintainers, but everyone is invited
  58     * feedback has to consider design, functionality and style
  59     * simpler and clearer code preferred, even if original code works fine
  60
  61 2. accepted patches merged into next branch
  62
  63 3. further testing done by community, including CI build tests
  64
  65 4. if no new problems or discussions showed up, acceptance into master
  66     * grace period for master: about 3 days
  67     * urgent fixes may be applied sooner
  68
  69 github facilities are not used for the review process so that people can follow
  70 all changes and related discussions at a single stop, the mailing list. This
  71 may change in the future if github should improve their email integration.
  72
  73
  74 Areas of responsibility
  75 -----------------------
  76
  77 Jailhouse is rather small. Nevertheless, there are different people involved in
  78 different areas of its code. The following list shall give an overview on who
  79 is working in which area and should be involved when discussing changes:
  80
  81 Jan Kiszka <jan.kiszka@siemens.com>:
  82  - overall Jailhouse maintenance
  83  - committer to official repository
  84
  85 Valentine Sinitsyn <valentine.sinitsyn@gmail.com>:
  86  - AMD64 support
  87
  88 Henning Schild <henning.schild@siemens.com>:
  89  - inter-cell communication
  90  - configuration file generator