This is a tutorial how to create a Debian package for Astropy Affiliated Packages. The tutorial consists of three parts:
Note that there is a Sprint Meeting in Heidelberg at 2015-08-14 where we organize a packaging tutorial.
Announce that you want to create a package
One of the first steps is to issue an "Intent To Package" (ITP). This will inform the Debian community that you are working on this package and will prevent that other start with the same package in parallel.
The mail should be sent as a bug report to email@example.com with the subject ITP: wcsaxes -- Framework for plotting astronomical and geospatial data It has the following contents:
Package: wnpp Owner: Ole Streicher <firstname.lastname@example.org> Severity: wishlist X-Debbugs-Cc: email@example.com,firstname.lastname@example.org,email@example.com
These are the "pseudo-header" lines. They inform the Debian bug system about the package (`wnpp`, which is the pseudo package that collects all reports of this kind) and the bug owner. The Severity should be set to "wishlist".
Usually, the bug report gets automatically forwarded to the debian-devel mailing list. In our case (astronomy related python packages), it would be wise to forward it to the debian-astro and debian-python mailing lists as well. This will make sure that the ITP is recognized by all relevant people. The reason to put it here is that the mail is then forwarded after it got its bug number.
The pseudo-header lines are divided from the rest of the mail by an empty line.
The next part contains the main information in a more-or-less formal way:
* Package name : WCSAxes Version : 0.3 Upstream Author : Thomas Robitaille <firstname.lastname@example.org> * URL : https://github.com/astrofrog/wcsaxes * License : BSD-3-Clause Programming Lang: Python Description : Framework for plotting astronomical and geospatial data
One can add additional stuff then:
WCSAxes is a framework for making plots of Astronomical data in Matplotlib. It is affiliated with the Astropy project and is intended for inclusion in the Astropy package once stable. I am packaging this mainly as an example for a small Debian packaging tutorial/workshop for astropy affiliated packages . It will maintained within the Debian Astronomy Working Group. A git repository will be created on alioth . Best regards Ole  http://www.astropy.org/affiliated/index.html  https://anonscm.debian.org/cgit/debian-astro/packages/wcsaxes.git
Apply for membership on debian-astro
Since the package is astronomy-related, it is wise to put it under collaborative maintenance of the debian-astro team. This way, other members of the team can contribute to the packaging repository and help you solving issues.
For this, you first need to create an account on the "alioth" computer. Once you got your account (don't worry about the "guest" suffix; you are a full member, and not just a guest!), you can request a membership in debian-astro.
You should also upload an ssh key to alioth, so that you can ssh to this machine. This will be needed later to create and access the git repository of your package. More info about ssh into alioth can be found in the Wiki.
There are also a number of mailing lists which are recommended to subscribe:
debian-astro: for all questions related to your astronomy package. We are a small community and will try to help you there.
debian-python: They will help with python related issues.
debian-mentors: the Newcomer mailing list. This one is really helpful for any question about packaging.
Setup git repository
It is strongly encouraged that the packaging is done within a git repository hosted on alioth. Even if you are an upstream developer, it is not a good idea to have debian files within the upstream source code; this will cause problems.
To create a git repository, ssh to alioth, and then do a
$ cd /git/debian-astro/packages $ ./setup-repository wcsaxes "Framework for plotting astronomical and geospatial data"
On you development machine, you can now clone the repository:
$ git clone git+ssh://email@example.com/git/debian-astro/packages/wcsaxes.git
and you are ready for packaging.
Prepare your development tools
Ideally, your development machine should run Debian itself. However, derivatives like Ubuntu or Mint are usable here as well.
For the development, you will need to sudo from your normal account. To enable this, put yourself into the sudo group.
First, install the packages needed for development:
$ sudo apt-get install devscripts pbuilder pristine-tar git quilt lintian \ python-setuptools python3-setuptools python-astropy-helpers python3-astropy-helpers
The packaging itself should not be done directly on your environment, but within a chroot environment with a clean Debian installation. This is the purpose of the "pbuilder" package. To set it up, you should do the following (this will take some time):
$ sudo pbuilder create
On Ubuntu or Mint you need to create a ~/.pbuilderrc file first to specify the distribution:
Setup the basic information for the development tools. Create the file ~/.devscripts with the following contents (replace with your own name and E-mail):
DEBFULLNAME="Ole Streicher" DEBEMAILfirstname.lastname@example.org
Setup the program to patch the original sources. In ~/.quiltrc, put
QUILT_PATCHES=debian/patches QUILT_NO_DIFF_INDEX=1 QUILT_NO_DIFF_TIMESTAMPS=1 QUILT_REFRESH_ARGS="-p ab"
There is quite a lot documentation available that you can check for further information. The most important pages are
Debian New Maintainers' Guide -- tutorial for simple package
Debian Packaging Tutorial -- slides-based overview of Debian packaging
Developers Reference -- advanced guide etc.
The policies describe the basic rules to follow when packaging: