wiki/src/contribute/merge_policy/common_rules.mdwn

   1 [[!meta title="Git merge policy: common rules"]]
   2
   3 ## Documentation is not optional
   4
   5 When writing Tails code, one commits to adapt the design and end-user
   6 documentations accordingly in a timely manner, writing brand new
   7 chapters if needed.
   8
   9 ### Design documentation
  10
  11 As a side note, best is generally to write specification and design
  12 documentation before implementing changes; among other very valid
  13 reasons to do so, it may avoid doing work that won't be applied ever,
  14 or be reverted later, because of a faulty design that was reviewed and
  15 diagnosed only when the implementation was up and running. On the
  16 other hand, we're not great fans of over-engineering and we do know
  17 proceeding like this is not always an option, as the right design
  18 sometimes arises from erratic implementation attempts.
  19
  20 ### User documentation
  21
  22 See our [[documentation guidelines|contribute/how/documentation/guidelines]].
  23
  24 Verify that your changes do not affect the rest of the user documentation and
  25 FAQ. If so, fix it in your development branch so that it gets automatically
  26 integrated when your branch get released.
  27
  28 Regarding the FAQ, don't write new questions in advance but make sure that the
  29 existing ones are still correct.
  30
  31 ## Test your code
  32
  33 A branch proposed for review and merge must have been tested when applied
  34 against either experimental, or against the target branch(es) of the requested
  35 merge.
  36
  37 ## Do not break the build... or get reverted
  38
  39 Noone should ever push changes breaking the build into the shared Git
  40 repository. On the other hand, this may happen since preliminary,
  41 untested changes may in some circumstances land into our `devel`
  42 branch to be reviewed and get more exposure.
  43
  44 If you find the `devel` branch in a non-building state and can
  45 identify the root cause of it to a recent commit, fix it if you wish,
  46 but don't let it disturb you otherwise: just revert the faulty commit
  47 and [[inform the other developers|contribute/talk]] so that the author knows
  48 s/he needs to fix his/her stuff before reapplying it at a later point.