hacking.txt

   1 = Hacker's Guide to irker =
   2
   3 == Design philosopy ==
   4
   5 Points to you if some of this seems familiar from GPSD...
   6
   7 === Keep mechanism and policy separate ===
   8
   9 Mechanism goes in irkerd.  Policy goes in irkerhook.py
  10
  11 irkerd is intended to be super-simple and completely indifferent to
  12 what content passes through it.  It doesn't know, in any sense, that
  13 the use-case it was designed for is broadcasting notifications from
  14 version control systems. irkerhook.py is the part that knows about how
  15 to mine data from repositories and sets the format of notifications.
  16
  17 === If you think the mechanism needs an option, think again ===
  18
  19 Because irkerhook.py does policy, it takes policy options. Because
  20 irkerd is pure mechanism, it shouldn't need any.  If you think it
  21 does, you have almost certainly got a bug in your thinking.  Fix
  22 that before you modify code.
  23
  24 === Never configure what you can autoconfigure ===
  25
  26 Human attention is more expensive than machine time.  Humans are
  27 careless and failure-prone.  Therefore, whenever you make a user tell
  28 your code something the code can deduce for itself, you are
  29 introducing unnecessary inefficiency and unnecessary failure modes.
  30
  31 This, in particular, is why irkerhook.py doesn't have a repository
  32 type switch. It can deduce the repo type by looking, so it should.
  33
  34 == Release procedure ==
  35
  36 1. Check for merge requests at https://gitorious.org/irker
  37
  38 2. Do 'make pylint' to audit the code.
  39
  40 3. Run irk with a sample message; look at #irker on freenode to verify.
  41
  42 4. Bump the version numbers in irkerd and irkerhook.py
  43
  44 5. Update the NEWS file
  45
  46 6. make release
  47
  48 == Thanks where due ==
  49
  50 Alexander van Gessel (AI0867) <ai0867@gmail.com> contributed the
  51 Subversion support in irkerhook.py. Since the 1.0 release he has
  52 kept as close an eye on the code as the author and has fixed at least
  53 as many bugs.
  54
  55 Daniel Franke <dfoxfranke@gmail.com> performed a security audit of irkerd.
  56
  57 Georg Brandl <georg@python.org> contributed the Mercurial support in
  58 irkerhook.py and explained how to make Control-C work right.
  59
  60 Laurent Bachelier <laurent@bachelier.name> fixed the Makefile so it
  61 wouldn't break stuff and wrote the first version of the external
  62 filtering option.
  63
  64 dak180 (name withheld by request) wrote the OS X launchd plist.
  65
  66 Wulf C. Krueger <philantrop@exherbo.org> wrote the systemd
  67 installation support.
  68
  69 Other people on the freenode #irker channel (Kingpin, fpcfan,
  70 shadowm, Rick) smoked out bugs in irkerd before they could seriously
  71 bug anybody.
  72