From: Eric S. Raymond <esr@thyrsus.com>
Date: Mon, 1 Oct 2012 00:07:38 +0000 (-0400)
Subject: Add hacking.txt.
X-Git-Tag: 1.3~24
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=d2f6c7fa8234487275cbc4147d49f1517e0e1d22;p=irker.git

Add hacking.txt.
---

diff --git a/Makefile b/Makefile
index f980bf2..de3a7ca 100644
--- a/Makefile
+++ b/Makefile
@@ -37,7 +37,7 @@ pylint:
 	@pylint --output-format=parseable $(PYLINTOPTS) irkerhook.py
 
 
-SOURCES = README COPYING NEWS BUGS install.txt security.txt \
+SOURCES = README COPYING NEWS BUGS install.txt security.txt hacking.txt \
 	irkerd irkerhook.py Makefile irkerd.xml irkerhook.xml irker-logo.png
 
 version:
diff --git a/README b/README
index aae724a..844a4e4 100644
--- a/README
+++ b/README
@@ -19,5 +19,7 @@ Due to the abrupt death of cia.vc on September 24 2012 the
 initial release of this software was a bit rushed.  See the file
 BUGS for known problems.
 
+Please read the file hacking.txt before modifying this code.
+
 						Eric S. Raymond
 						August 2012
diff --git a/hacking.txt b/hacking.txt
new file mode 100644
index 0000000..5133cab
--- /dev/null
+++ b/hacking.txt
@@ -0,0 +1,44 @@
+= Hacker's Guide to irker ==
+
+== Design philosopy ==
+
+Points to you if some of this seems familiar from GPSD...
+
+=== Keep mechanism and policy separate ===
+
+Mechanism goes in irkerd.  Policy goes in irkerhook.py
+
+irkerd is intended to be super-simple and completely indifferent to
+what content passes through it.  It doesn't know, in any sense, that
+the use-case it was designed for is broadcasting notifications from
+version control systems. irkerhook.py is the part that knows about how
+to mine data from repositories and sets the format of notifications.
+
+=== If you think the mechanism needs an option, think again ===
+
+Because irkerhook.py does policy, it takes policy options. Because
+irkerd is pure mechanism. it shouldn't need any.  If you think it
+does, you have almost certainly got a bug in your thinking.  Fix
+that before you modify code.
+
+=== Never configure what you can autoconfigure ===
+
+Human attention is more expensive than machine time.  Humans are
+careless and failure-prone.  Therefore, whenever you make a user tell
+your code something the code can deduce for itself, you are
+introducing unnecessary inefficiency and unnecessary failure modes.
+
+This, in particular, is why irkerhook.py doesn't have a repository
+type switch. It can deduce the repo type by looking, so it should.
+
+== Release procedure ==
+
+1. Do 'make pylint' to audit the code.
+
+2. Run irkerd and irkerhook.py; look at #irker on freenode to verify.
+
+3. Bump the version numbers in irkerd and irkerhook.py
+
+4. Update the NEWS file
+
+5. make dist; make release