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