HACKING: First cut

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/HACKING b/HACKING
new file mode 100644 (file)
index 0000000..2839200
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,91 @@
+Here are some hints and tips or working on src:dgit
+===================================================
+
+Program and source code layout
+------------------------------
+
+Most stuff is in the toplevel.
+Debian/ contains Perl modules, notably Debian/Dgit.pm.
+That module contains much shared code and is used by every package.
+
+The test suite is very useful for ad-hoc work, so see "Tests" below.
+
+Coding style
+------------
+
+I like to use perl "poetry mode" where ( ) are often elided.
+This is often nice and terse but there is a gotcha.  This
+   some_function ($a + 2), $b, $c
+is wrong, because the ( ) are treated as function call ( )
+for some_function.  When this is a risk, you have to write:
+   some_function +($a + 2), $b, $c
+
+Keep the line length to 75 at most please.
+
+i18n
+----
+
+In the Perl code we use these functions:
+
+ here:   meaning:                                           like, in C:
+  __      translate this message                             _ aka gettext
+  f_      this is a sprintf string to be translated          sprintf(_ ...
+  i_      mark for translation but do not translate here     gettext_noop
+
+See the info node `(gettext) Sources' for the complete semantics.
+
+The shell scripts are not translated right now.
+
+Running ad-hoc
+--------------
+
+You can run everything right out of the git tree, for ad hoc testing,,
+like this (supposing your dgit tree is in things/Dgit/dgit):
+
+  ~/things/Dgit/dgit/using-these dgit --some-option blah blah
+
+using-these will set PATH and PERLLIB so that programs and modules
+come from its own directory (obtained from $0).
+
+Tests, running and use for hacking
+----------------------------------
+
+The test cases are in bash and are in tests/tests/*.  They all use
+shell libraries tests/lib*.
+
+You can run it formally with autopkgtest, but you normally want to run
+tests in one of these two ways [1]:
+
+  tests/using-intree tests/tests/<some-test> 2>&1 |tee ../log
+  tests/run-all [tests/tests/<some shell glob>]
+
+These will leave their working stuff in ./tests/tmp/<name-of-test>.
+
+The test suite is often a nice way to set up situations for ad-hoc
+testing.  You can add "xxx" in the middle of one of the test cases to
+get it to crash at the right point.  Have an absolute cd like
+  cd ~/things/Dgit/dgit/tests/tmp/<some-test>
+in your shell history, because each time you run the test it will
+blow that directory away again.
+
+There are many env vars settings like
+   DGIT_TEST_DEBUG=          DGIT_TEST_DEBUG=-DDD
+   DGIT_TEST_DEBPUSH_DEBUG=  DGIT_TEST_DEBPUSH_DEBUG=x
+which can be used to control the level of debug output from
+individual programs run by the test suite.
+
+Editing/adding tests
+--------------------
+
+Things in tests/setup/ generate canned starting points.  You can run
+them by hand, but when they are imported by other tests they are not
+automatically regenerated by default.  So if you are editing one of
+those, git-clean is your friend.
+
+debian/tests/control is autogenerated by a rule in debia/rules.  If
+making actual releases, you must rerun that.
+
+[1] The test suite and libraries, when run without any special
+environment variables, expect to be run via DEP-8 (autopkgtest) - so
+they want an to everything out of PATH and /usr.  But there are also
+arrangements to honour environment variables set by using-intree.