Packaging Policy

This Packaging Policy describes the packaging rules that packages maintained by the Debian Islamic Project should follow. The aim is to define a common set of rules to make maintenance easier for everyone involved in the project.

It is not normative as the Debian Policy. If rules or suggestions in this document conflict with the Debian Policy it is a bug in this document.

debian/* files

The following sections describe the changes to the control files stored in the source package's debian/ directory.

debian/control

Maintainer and Uploaders Fields

The Maintainer field should be Debian Islamic Maintainers <debian-islamic-maintainers@lists.alioth.debian.org>.

You should also add yourself to the Uploaders field. Doing so shows your involvement and interest in the package. Developers listed in Uploaders will take care of maintenance, bug reports and other QA work, helped by the Debian Islamic team.

Vcs-Git and Vcs-Browser Fields

If you have your package under version control in the Debian Islamic Repository, you must set the Vcs-Git and Vcs-Browser fields.

The Vcs-Git field should contain the package repository URL, namely git://git.debian.org/git/debian-islamic/packages/YourPackage.git.

The Vcs-Browser field should point to the web view of your package repository, namely http://git.debian.org/?p=debian-islamic/packages/YourPackage.git.

Homepage Field

If an upstream homepage exists, the Homepage field should be set to the upstream homepage URL.

debian/copyright

If possible, the machine-readable format should be used.

The license of the packaging work should either match the license of the upstream sources or have a license that is even more free than the upstream license. For example, you should avoid licensing your packaging work under GPL if the upstream license is BSD, even though they are compatible.

debian/watch

If possible, a debian/watch file should be added so upstream releases can be tracked automatically.

debian/changelog

We use the debian revision to count our releases to the debian archive, not internal steps. So if and only if you do the first change after a release, you add another debian/changelog entry dch -i. Note that the name and email address in the debian/changelog entry (i.e. after --) should be present in Uploaders: in debian/control (otherwise lintian will think that you are doing an NMU).

If you change something that has to be noted in debian/changelog, just add a line to the current entry (dch -a). The [firstname lastname] markers added by dch are okay to give credit to non-upload-permitted contributors.

When you put UNRELEASED in the release field, then this means the package is work in progress. It is not uploaded yet and is not ready to be uploaded, it still needs some work before it is in a state to be released.

Examples

In this section you will find example debian/control and debian/copyright files that you can use as a template and modify as needed. Taken from zakat calc packages

Example 1.1. Example debian/control for package "foo"

Source: zakat-calc
Section: misc
Priority: extra
Maintainer: Debian Islamic Maintainers <debian-islamic-maintainers@lists.alioth.debian.org>
Uploaders: Mahyuddin Susanto <udienz@gmail.com>
Build-Depends: debhelper (>= 8),
                gambas2-runtime (>= 2.0),
                gambas2-gb-form (>= 2.0),
                gambas2-dev,
Standards-Version: 3.9.1
Homepage: http://sourceforge.net/projects/zakat-calc/
Vcs-git: git://git.debian.org/debian-islamic/packages/zakat-calc.git
Vcs-Browser: http://git.debian.org/?p=debian-islamic/packages/zakat-calc.git;a=summary

Package: zakat-calc
Architecture: any
Depends: ${misc:Depends},
        gambas2-runtime (>= 2.14),
        gambas2-gb-form (>= 2.14),
        gambas2-gb-pcre
Description: Zakat Calc provide zakat calculations for Muslim
 A program to predict how much Muslim can spend zakat
 especially for Muslim. Zakat Calc is a project under
 Sabily Project. This application write under gambas

Example 1.2. Example debian/copyright for package "foo" under GPL

Format: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=153
Upstream-Name: Sabily Zakat
Source: http://sourceforge.net/projects/zakat-calc/
Upstream-Contact: Soire Meira <soirem08@gmail.com>

Files: *
Copyright: 2010, Soire Meira <soirem08@gmail.com>
License: GPL-3+

Files: debian/*
Copyright: 2010-2011, Mahyuddin Susanto <udienz@gmail.com>
License: GPL-3+

License: GPL-3+
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.

 This package is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.

 On Debian systems, the complete text of the GNU General
 Public License version 3 can be found in `/usr/share/common-licenses/GPL-3'.

Version Control

The Debian Islamic Project has agreed to use Git as their preferred Version Control System (VCS).

Because of Git's nature, each package exists in its own repository. The term "repository" is also used for the location where all packages are stored. It is used in the following sections as defined below:

Git Repository means a (bare) Git repository, containing history information.

Package Repository means a Git Repository that stores packaging information.

Debian Islamic Repository means the location where all package repositories are stored.

The Debian Islamic Repository

The Debian Islamic Repository is located on Alioth in the directory /git/debian-islamic/. All group members have write access to the directory.

The Debian Islamic Repository is structured by a directory hierarchy containing several Git Repositories and other directories. It is structured like this:

debian-islamic/
+- homepage(.git?)
+- packages/
   +- bar.git
   +- baz.git
   +- foo.git
+- policy.git
+- tasks(.git?)
+- tools(.git?)
+- ...

Package Repositories have to be placed in the packages/ sub-directory. They should follow the guidelines in the Package Repositories section.

Package Repositories

The following sections explain the preferred Package Repository layout.

Repository Layout and Structure

Each Package Repository has to be stored as bare Git Repository inside the packages/ sub-directory of the Debian Islamic Repository.

The Package Repository name has to be the name of the source package followed by a .git extension. A source package named foo is therefore stored in a Package Repository named foo.git.

Branches

All Package Repositories should contain a common set of branches in order to ease maintenance.

All Debian-specific changes (such as the debian/ directory) should go to a branch named debian or master. If you use several branches to organize your changes, the debian branch should be treated as integration branch.

If upstream sources are included in the Package Repository they should be stored in a branch named upstream. It can either store upstream sources from a VCS or source tar-ball snapshots.

It is recommended to use pristine-tar to be able to restore upstream tar-balls from the source files in the Package Repository. The delta files produced by pristine-tar should be stored in the pristine-tar branch.

Tags

All imports of source tar-balls or upstream releases (if tracked in the Package Repository) should be tagged as upstream/${VERSION}. For example, the 1.2.3 release of a package should have a tag upstream/1.2.3.

Accordingly, all Debian releases of a package should be tagged debian/${DEB-VERSION}. For example, the second Debian release of the example package in the last paragraph should have a tag debian/1.2.3-2.

Commit Messages

Each Package Repository should add a commit hook that sends commit messages to the <debian-islamic-commits@lists.alioth.debian.org> mailing list.

The recommended way is to use the git-commit-notice script on Alioth. To setup the hook, login to Alioth and change into your Package Repository directory. There you can execute:

$ git config --add hooks.mailinglist "debian-islamic-commits@lists.alioth.debian.org"
$ cat >hooks/post-receive <<END
#!/bin/sh
exec /usr/local/bin/git-commit-notice
END
$ chmod 0775 hooks/post-receive

Build Systems

Package maintainers are free to use any build system for packaging (or none at all), but Debhelper is recommend. Patch Systems

Package maintainers are free to use any patch system for packaging but quilt is preferred.

If a package is stored in a Package Repository a patch system is not needed technically but the maintainer is free to use one nevertheless.

ITP/RFP reports

Intend To Package (ITP)

When a Debian Islamic Maintainer is sending an ITP to the BTS, <debian-islamic-maintainers@lists.alioth.debian.org> should one of the receiver of this ITP. Therefore, members of the team will be informed of the on-going work and could provide help.

Request For Packaging (RFP)

If a RFP of a scientific software is sent to the BTS, this one could be assigned to the team and added to the our package list.