Guidelines for developers wishing to contribute to Debian-Edu

The Debian-Edu/Skolelinux project is a custom Debian GNU/Linux distribution. It builds its own CDs based on Debian packages and some project-specific packages.

We use Subversion for version control and management of the code. The repository is placed on svn.debian.org. The project is part of the Custom Debian Distributions group, and we use Alioth for management of the contributors. In order to contribute to the project you will need an account at Alioth. This is accomplished by visiting the user portal at http://alioth.debian.org and creating an account.

Just follow the instructions, reply to any email messages that may be sent, and you will in the end be rewarded with an account. Most people are not Debian Developers, and they will be identified as <user>-guest. Registered Debian Developers don't have to live with being guests.

Once you have an account, the next step is to check out the Subversion tree. If Subversion is a new tool to you, we suggest a visit to the project site to find documentation on its use. To install it on your Debian system, use

# apt-get install subversion subversion-tools

To get you going, the command to check out the debian-edu code is:

$ svn co svn+ssh://user-guest@svn.debian.org/svn/debian-edu/trunk debian-edu

At this stage you have a copy of our code locally on your computer, and the means to modify it. We suggest you use your powers to influence the contents of the CD with some care. Improperly tested solutions will hamper the development and draw attention away from the forward movement.

There are innumerable ways in which to contribute. However, the main method for reporting errors and suggesting improvements is our bugs database. If Bugzilla is a new tool to you, please look at their project site for information on its use.

It is of more benefit to the project that new developers fix bugs rather than making new additions nilly willy. Please consider squashing some bugs before suggesting new features and applications.

Once you have decided on a bug that looks a good candidate for your efforts, make sure that you have a current installation of Debian-Edu to test the fixes. Once you are satisfied that the work you have done will close the bug, check in the changes to the code using svn. Maybe before you decide to upload a new version of the package you coordinate your work with the other developers on IRC (irc.debian.org channel #debian-edu) so that you can't shoot in someones leg and others are informed. Don't forget to make a set of comments to the changes when you check in. Also remember to update the debian/changelog file to record your efforts and give yourself proper credit for the work. At the top line you should put the number of the svn revision. Normally you check in the changes, note the svn revision number, make the changes to debian/changelog and put the noted number plus one (it gets upped one when you check in the changelog) in the top line of debian/changelog.

Once the changelog is updated and all the files checked in, the package you are working on can be rebuilt. You will need a number of tools, all of which are available from the normal apt repositories. Use this list as a guide:

The package you are working on should build cleanly using the command

$ svn-buildpackage -rfakeroot -us -uc

from the directory immediately above the debian/ directory (using the options -us -uc to svn-buildpackage -rfakeroot will prevent a GPG signing).

$ svn-buildpackage -rfakeroot -us -uc

As usual the package files will be located in the build-area directory of the svn repository.Then please change into the build-area directory and check the package using the commands lintian and linda. If you get any error messages you can make the check programms more verbose with the -i option. If you think the package is ready for uploading to Debian-Edu please use the command debsign to sign the .dsc and .changes files with your gpg-key. $ debsign -kkeyid *.changes

Then all other developers can verify who did the upload and the archive software will check if you are a valid uploader.

In order to get the package onto the CD it needs to be uploaded into the archive. Upload the package using the dput/dupload tool:

$ dput skolelinux *.changes or $ dupload --to skolelinux *.changes

That is all you need to do before the CD builds. Give yourself fifteen minutes to get a cup of coffe or a little stretch on the couch while the CD builds. After the CD is finished, you need to sync your current image of the CD with that on developer.skolelinux.no so that you have an updated version to test with. One way to sync the CD is to use rsync, then you download only the changes between the previous version and the current. This is a command to do that:

{{{$ rsync --verbose --times \ rsync.skolelinux.no::skolelinux-sarge/debian-edu-i386-binary-1.raw \ ~/images/de-sarge-current.iso}}}

And that's it. Now you should have a version of the CD that includes the changes you have made. The next step is to verify that the changes actually do what you think. How that is accomplished depends entirely on the nature of the changes. It may be necessary with a reinstall or it could be enough just to update the package on a current installation of Debian Edu.

Good luck!

Adding a new package to the CD

First copy/hardlink the package into the dists/sarge/... directory as described above, to make it available for the CD building script.

The primary method is to add the package to the debian-edu task lists. The packages listed here are used to generate a list of packages to put on the CD.

If this is not an option, there are two alternatives. One is to update the debian-edu-svn:src/build/CD/extrapkgs.txt, and add the name of the new package to the list. The packages listed here will be added to the end of the list of packages to put on the CD, and might not make it into the CD.

The other is debian-edu-svn:/src/build/CD/hintpkgs.txt, listing packages to add earlier in the package list, to control which package alternative is selected when the CD build need to make choices. The packages listed here are added just after the base packages.