You would like to contribute to dpkg? Perfect, here a few simple steps to get you started.
Contents
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
Click here and fill the form to subscribe to our mailing list (debian-dpkg@lists.debian.org). You'll have to confirm your subscription by replying to a mail.
Click here and fill the form to subscribe to dpkg via the Package Tracking System. You just have to update the email field, leave the rest unchanged. You'll have to confirm your subscription by replying to a mail. After that you'll receive the bug traffic but also the Git commit notices.
- If you use IRC, join #debian-dpkg on irc.debian.org (OFTC) and put it in your auto-join list. Feel free to introduce yourself.
- Clone the 2Â required Git repositories:
$ git clone git://git.debian.org/dpkg/dpkg.git $ git clone git://git.debian.org/dpkg/pkg-tests.git
Add some useful remote repositories (those of GuillemJover and RaphaelHertzog):
$ cd dpkg $ git remote add guillem git://git.hadrons.org/git/debian/dpkg/dpkg.git $ git remote add buxy git://git.debian.org/~hertzog/dpkg.git $ git fetch guillem && git fetch buxy $ cd ../pkg-tests $ git remote add guillem git://git.hadrons.org/git/debian/dpkg/pkg-tests.git $ git remote add buxy git://git.debian.org/~hertzog/pkg-tests.git $ git fetch guillem && git fetch buxy
Send a mail to debian-dpkg@lists.debian.org to present you and to inform us that you want to try to help.
Learn how to submit 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.
- Start from a clean copy of the master branch:
$ git checkout -b pu/mybranch master
- Do your changes and commit the result (multiple times if you want to split them over multiple commits):
$ vim .... $ git add ... $ git commit
- Generate the corresponding patches:
$ git format-patch master
- Send the *.patch files just generated by email to the corresponding bug. Tag the bug "patch".
Learn how to run the functional test-suite
dpkg has some non-regression & unit tests integrated in its main repository (see lib/dpkg/test/, scripts/t/, utils/t/) but those tests do not cover the run-time behaviour of dpkg itself. Those are in the separate repository "pkg-tests".
The 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) so you should install the version of dpkg that you want to test.
For those reasons, you might prefer to only run the 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 (regressions).
Help triage/reproduce the bugs.
Provide non-regression tests to be merged in pkg-tests.git
Provide patches for confirmed bugs.
Help us review and update patches, see ReviewMergeQueue.
Help us complete the projects on our roadmap.
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 GPG key to avoid APT's error due to unauthenticated packages:
$ wget -O - http://jenkins.grml.org/debian/C525F56752D4A654.asc | sudo apt-key add -
If you're more adventurous, you can run Raphael's test-build branch, it's also based on the latest git version but also includes some unmerged branches that are still being worked on.
deb http://jenkins.grml.org/debian dpkg-test main
For both repositories, 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 us deal with the flow of incoming bugs:
- Fix the easy bugs (like those that only require changing the documentation) by yourself and provide a patch that the maintainers can quickly apply.
Try to reproduce the reported problems. If you manage to reproduce it, tag the bug confirmed (bts tag <bugnumber> + confirmed). If possible propose a non-regression test that can be used to reproduce it and to verify if a patch works as expected.
- If there's not enough information to properly reproduce the problem, ask the submitter to provide the missing information and tag the bug "moreinfo" in the mean time.
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 non-regression test
Adding a new non-regression test to pkg-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).