README.coding

   1 Some small guidelines if you want to help coding
   2 ------------------------------------------------
   3
   4 First: I'm always happy to get patches for Dak. I like to merge
   5 enhancements, bugfixes, whatever. The more, the better.
   6
   7 Now, to not annoy us all by coming up with small fixes to patches
   8 multiple times before I merge them, lets write down a few small
   9 guidelines we all should follow. Yes, the current dakV1 code sure won't
  10 follow this everywhere, but no need to have new code be the same. :)
  11
  12 I very much prefer git trees to merge from over simple patches,
  13 especially if you do lots of changes. (No need for a full git tree for a
  14 one-off fix). Reason is simple - its much easier to work with. And it is
  15 also way better in terms of assigning who did what, who has to earn the
  16 praise. :)
  17 In case you have more than one feature you want me to merge, one branch
  18 per feature please. If the location of your git tree is stable and
  19 doesn't change every second day I'm also very grateful. :)
  20
  21
  22 Code related:
  23
  24 - Use readable and self-speaking variable names.
  25
  26 - Its 4 spaces per indentation. No tab.
  27
  28 - You want to make sure to not add useless whitespaces. If your editor
  29   doesn't hilight them, Git can help you with that, just set
  30   [color "diff"]
  31      new = green
  32      old = red
  33      frag = yellow
  34      meta = cyan
  35      commit = normal
  36   in your ~/.gitconfig, and a git diff should hilight them.
  37   Even better, if you enable the hook pre-commit in your copy of the dak
  38   code (chmod +x most probably), git will refuse to commit such things.
  39
  40 - Describe *every* function you write using a docstring. No matter how small.
  41
  42 - Also describe every file.
  43
  44 - Don't forget the Copyright/License header in a file. We expect GPLv2 :)
  45
  46 - Don't write long functions. If it goes above a sane limit (like 50
  47   lines) - split it up.
  48
  49 - Look at / read http://www.python.org/dev/peps/pep-0008/
  50
  51
  52 VCS related:
  53
  54 - History rewriting is considered bad.
  55
  56 - Always have a "Signed-off-by" line in your commit. `git commit -s`
  57   automatically does it for you. Alternatively you can enable the hook
  58   "prepare-commit-msg, that should also do it for you.
  59
  60 - Write good, meaningful, commit messages. We do not have a Changelog
  61   file anymore, the git commit is *the* place to tell others what you
  62   did.
  63   Also, try to use the standard format used in the Git world:
  64
  65     First comes a summary line, of around 72 caracters at most.
  66
  67     Then, a blank line, and as many lines and paragraphs as needed
  68     to describe the change in detail. Beware, though, of including
  69     in the commit message explanations that would be better to have
  70     as comments in the code itself!
  71
  72     Signed-off-by: Your Name <and@address.com>