summaryrefslogtreecommitdiff
path: root/HACKING
blob: 2839200f29a25a406f324ba2c004726ff4ca2a85 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
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.