diff options
authorIan Jackson <>2019-07-22 15:55:22 +0100
committerIan Jackson <>2019-07-22 15:55:31 +0100
commit8af179949e9c5c01c7202aa5efbe3c0be27310ff (patch)
parentc692a79177069b52731bba1d3c495e521b6e4449 (diff)
HACKING: First cut
Signed-off-by: Ian Jackson <>
1 files changed, 91 insertions, 0 deletions
diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..2839200
--- /dev/null
@@ -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/
+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.
+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
+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.