HACKING

   1 Here are some hints and tips or working on src:dgit
   2 ===================================================
   3
   4 Program and source code layout
   5 ------------------------------
   6
   7 Most stuff is in the toplevel.
   8 Debian/ contains Perl modules, notably Debian/Dgit.pm.
   9 That module contains much shared code and is used by every package.
  10
  11 The test suite is very useful for ad-hoc work, so see "Tests" below.
  12
  13 Coding style
  14 ------------
  15
  16 I like to use perl "poetry mode" where ( ) are often elided.
  17 This is often nice and terse but there is a gotcha.  This
  18    some_function ($a + 2), $b, $c
  19 is wrong, because the ( ) are treated as function call ( )
  20 for some_function.  When this is a risk, you have to write:
  21    some_function +($a + 2), $b, $c
  22
  23 Keep the line length to 75 at most please.
  24
  25 i18n
  26 ----
  27
  28 In the Perl code we use these functions:
  29
  30  here:   meaning:                                           like, in C:
  31   __      translate this message                             _ aka gettext
  32   f_      this is a sprintf string to be translated          sprintf(_ ...
  33   i_      mark for translation but do not translate here     gettext_noop
  34
  35 See the info node `(gettext) Sources' for the complete semantics.
  36
  37 The shell scripts are not translated right now.
  38
  39 Running ad-hoc
  40 --------------
  41
  42 You can run everything right out of the git tree, for ad hoc testing,,
  43 like this (supposing your dgit tree is in things/Dgit/dgit):
  44
  45   ~/things/Dgit/dgit/using-these dgit --some-option blah blah
  46
  47 using-these will set PATH and PERLLIB so that programs and modules
  48 come from its own directory (obtained from $0).
  49
  50 Tests, running and use for hacking
  51 ----------------------------------
  52
  53 The test cases are in bash and are in tests/tests/*.  They all use
  54 shell libraries tests/lib*.
  55
  56 You can run it formally with autopkgtest, but you normally want to run
  57 tests in one of these two ways [1]:
  58
  59   tests/using-intree tests/tests/<some-test> 2>&1 |tee ../log
  60   tests/run-all [tests/tests/<some shell glob>]
  61
  62 These will leave their working stuff in ./tests/tmp/<name-of-test>.
  63
  64 The test suite is often a nice way to set up situations for ad-hoc
  65 testing.  You can add "xxx" in the middle of one of the test cases to
  66 get it to crash at the right point.  Have an absolute cd like
  67   cd ~/things/Dgit/dgit/tests/tmp/<some-test>
  68 in your shell history, because each time you run the test it will
  69 blow that directory away again.
  70
  71 There are many env vars settings like
  72    DGIT_TEST_DEBUG=          DGIT_TEST_DEBUG=-DDD
  73    DGIT_TEST_DEBPUSH_DEBUG=  DGIT_TEST_DEBPUSH_DEBUG=x
  74 which can be used to control the level of debug output from
  75 individual programs run by the test suite.
  76
  77 Editing/adding tests
  78 --------------------
  79
  80 Things in tests/setup/ generate canned starting points.  You can run
  81 them by hand, but when they are imported by other tests they are not
  82 automatically regenerated by default.  So if you are editing one of
  83 those, git-clean is your friend.
  84
  85 debian/tests/control is autogenerated by a rule in debia/rules.  If
  86 making actual releases, you must rerun that.
  87
  88 [1] The test suite and libraries, when run without any special
  89 environment variables, expect to be run via DEP-8 (autopkgtest) - so
  90 they want an to everything out of PATH and /usr.  But there are also
  91 arrangements to honour environment variables set by using-intree.