You would like to contribute to dpkg? Perfect, here a few simple steps to get you started.

Pre-requisites

You should know either Perl or C if you want to contribute code. If you want to contribute only to documentation, you should learn groff (groff_man(7)) for the manual pages and be familiar with PO files used for translating the documentation.

Ideally you have some packaging experience and you know what the various dpkg tools do. You can learn on the fly but it will require some supplementary efforts to train yourself when you're not familiar with something.

Initial setup

$ git clone https://anonscm.debian.org/git/dpkg/dpkg.git
$ git clone https://anonscm.debian.org/git/dpkg/dpkg-tests.git

$ cd dpkg
$ git remote add guillem https//git.hadrons.org/git/debian/dpkg/dpkg.git
$ git fetch guillem
$ cd ../dpkg-tests
$ git remote add guillem https://git.hadrons.org/git/debian/dpkg/dpkg-tests.git
$ git fetch guillem

Submitting a patch

If you're new to git, here's a short tutorial for this specific task. Don't stop at this, you should really learn Git. Start with this tutorial. You should learn how to manage "topic branches", how to rebase them, etc.

$ git checkout -b pu/mybranch master

$ vim ....
$ git add ...
$ git commit

$ DPKG_DEVEL_MODE=1 make check

$ git format-patch master

Running the functional test-suite

dpkg has some non-regression & unit tests integrated in its main repository (see t/, lib/dpkg/t/, src/t/, utils/t/, scripts/t/) but those tests do not cover the run-time behaviour of dpkg itself. Those are in the separate repository "dpkg-tests".

The functional test suite requires root rights and will manipulate the root filesystem (though only on paths that should not be used on a normal installation). It will test the system binaries (/usr/bin/dpkg, /usr/bin/dpkg-deb, etc) by default, so you should install the version of dpkg that you want to test, but it can also use the binaries from the build-tree (set DPKG_BUILDTREE in the environment or .pkg-tests.conf).

For those reasons, you might prefer to only run the functional test-suite in a chroot.

Running the test suite is then only a matter of calling make test. If you want to execute a single test, you can do make <name>-test where <name> is the name of the directory containing the test.

If the test-suite fails, you'll see an error message of make like this:

make: *** [test-case] Error 1
make: Leaving directory `...'

Note that in that case, you should probably run make test-clean to get rid of the cruft that was left installed on the system.

Find something to do

Use the Git version of dpkg and report problems

You can add the following repository to your sources.list. It always contains the latest build (for amd64/i386) of dpkg's master branch (built in a "sid" environment of course)

deb http://jenkins.grml.org/debian dpkg main

You will want to install the corresponding GnuPG key to avoid APT's error due to unauthenticated packages:

$ wget -O - http://jenkins.grml.org/debian/C525F56752D4A654.asc | sudo apt-key add -

You can report bugs with a simple mail to debian-dpkg@lists.debian.org. Often a notice on IRC (#debian-dpkg) is also enough but if you don't get a response there, please send an email.

Triage bugs

You can help dealing with the flow of incoming bugs:

Of course, you're welcome to do the same on old bugs too! In fact, that's where the help would be most useful.

Contribute a functional test

Adding a new non-regression functional test to dpkg-tests is really easy. Let's assume we want to add a new test that we call "foo". We'll create a new directory "t-foo" and put a simple Makefile inside:

TESTS_DEB := pkg-foo

include ../Test.mk

test-case:
        # All commands here must succeed for the test to pass
        $(DPKG_INSTALL) pkg-foo.deb
        $(call pkg_is_installed,pkg-foo)
        $(DPKG_PURGE) pkg-foo

test-clean:
        -$(DPKG_PURGE) pkg-foo

The variable TESTS_DEB defines a list of deb files to build. In this case, pkg-foo.deb will be built from the the t-foo/pkg-foo/ directory. It's up to you to add this directory with the proper files so that dpkg-deb -b pkg-foo creates the needed package.

The included Makefile snippet (../Test.mk) contains the required rules to build the deb files before running the test and to clean them. It also contains some macros (that you can use with $(call)) to ease writing some common tests.

The test-case target is the one that you must customize to execute the actual test. If you have many tests, you can use multiple targets and add them as dependencies of test-case:

test-case: test-foo-1 test-foo-2
test-foo-1:
        ...
test-foo-2:
        ...

The test-clean target is here to cleanup everything after the test, in particular if the test failed. Usually individual tests should clean up after themselves when they succeed so that further tests are not influenced by lingering files from tests previously run.

Once you're satisfied with your test-case, you should add it to the list of tests in the top-level Makefile (variable TESTS_PASS).

Teams/Dpkg/Contribute (last modified 2017-01-22 17:30:10)