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
Subscribe to the mailing list (debian-dpkg@lists.debian.org). You'll have to confirm your subscription by replying to a mail.
Fill the form on the Package Tracking System page to subscribe to PTS emails concerning dpkg. 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 https://git.dpkg.org/git/dpkg/dpkg.git $ git clone https://git.dpkg.org/git/dpkg/dpkg-tests.git
Add some useful remote repositories (those of GuillemJover):
$ 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
Send a mail to debian-dpkg@lists.debian.org to present you and to inform us that you want to try to help.
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.
- 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
Make sure it follows the coding style.
- Make sure it passes all test suites. For the functional test suite see below, for unit tests do:
$ DPKG_DEVEL_MODE=1 make check
- Make sure new tests are added covering major new features.
- Generate the corresponding patches:
$ git format-patch master
- Send the *.patch files just generated by email to the corresponding bug (and tag the bug "patch"), or to the mailing list.
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.
Refer the README file in dpkg-tests tree for any prerequisites, 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 functional tests to be merged in dpkg-tests.git
Provide patches for existing bugs.
Help review and update patches, see ReviewMergeQueue.
Help complete the projects on the 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 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:
- Fix the easy bugs (like those that only require changing the documentation) by yourself and provide a patch that can be quickly applied.
- If there is not enough information to properly reproduce the problem, ask the submitter to provide the missing information and tag the bug "moreinfo" and "unreproducible" in the mean time. These bugs are usually not actionable, and very unfortunately should be closed after a while to avoid cluttering the BTS.
- Try to reproduce the reported problems. If you manage to reproduce them, remove the "moreinfo" and "unreproducible" tags from the report. If possible propose a non-regression functional or unit test that can be used to reproduce it and to verify if a patch works as expected.
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).