Debian Islamic Policy Manual

Edited by

أحمد المحمودي

This document is based on the Debian Science policy manual authored by: 

Sylvestre Ledru

THIS IS AN INITIAL DRAFT!


Table of Contents

Introduction
About Debian Islamic
How to Contribute
Becoming a Member
1. Packaging Policy
Debian Control Files
debian/control
debian/copyright
debian/watch
debian/changelog
Examples
Version Control
The Debian Islamic Repository
Package Repositories
Build Systems
Patch Systems
ITP/RFP reports
Intend To Package (ITP)
Request For Packaging (RFP)
2. Communication vectors
Mailing Lists
Maintainer List
Commit List
Wiki
3. Maintenance of This Document
A. Help on Packaging
Packaging with Git
Creating a Repository
Importing Upstream Sources
Changes To The Upstream Sources
Publishing Your Repository

List of Examples

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

Introduction

About Debian Islamic

The main goal of the Debian Islamic project is to provide a system with all the most important Islamic software.

How to Contribute

FIXME

Becoming a Member

Before becoming a member you need to have on account on Alioth. If you do not have an account already, you can register one.

To request membership, login to Alioth and use the "Request to join" link on our Debian Islamic Alioth page. Your application will be processed quickly, insh'Allah.

Chapter 1. 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 Control 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 ".

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.

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

Source: foo
Homepage: http://foo.example.org/
Maintainer: Debian Islamic Maintainers <debian-islamic-maintainers@lists.alioth.debian.org>
Uploaders: Your Name <your.name@debian.org>
Vcs-Git: git://git.debian.org/git/debian-islamic/packages/foo.git
Vcs-Browser: http://git.debian.org/?p=debian-islamic/packages/foo.git

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

This package was downloaded from http://foo.example.org

Files: debian/*
Author: Your Name <your.name@debian.org>
Copyright: Copyright © 2008 Your Name <your.name@debian.org>
License: GPL-3+
 The Debian packaging is licensed under the GPL, version 3 or later,
 see below.

Files: *
Author: John Doe <john.doe@example.org>
Copyright: Copyright © 2007-2008 John Doe <john.doe@example.org>
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 program 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 the Debian GNU/Linux distribution in /etc/share/common-licenses/GPL.
  If not, see <http://www.gnu.org/licenses/>.

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

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 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, 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.

Chapter 2. Communication vectors

Mailing Lists

This section briefly explains the purpose of the mailing lists that are under the scope of Debian Islamic.

Maintainer List

The mailing list should be used for all packaging related issues, such as packaging questions and BTS messages. Team members are required to subscribe to this list.

Commit List

The mailing lists should collect all commit messages from commits to the Package Repositories. All Packages Repositories should have a commit hook that sends commit messages to this list.

Wiki

FIXME

Chapter 3. Maintenance of This Document

FIXME needs discussion

Appendix A. Help on Packaging

The following sections are not part of the Debian Islamic Policy Manual. They should provide useful information for contributors who are not familiar with the tools mentioned in this document.

Packaging with Git

This section will give you guide on packaging Debian packages with Git. Since Git is a very flexible tool, you can (and should!) adopt it to fit your work-flow best. "There is more than one way to do it", as the saying goes, so this document can not show all of them. It's supposed to help you if you are unfamiliar with using Git for packaging work. It is, however, not supposed to be a normative document that everyone has to follow.

Creating a Repository

Git repositories are nothing more than a directory with a special directory storing meta-data, named .git/. Creating and configuring the repository is pretty straight-forward:

$ mkdir foo && cd foo
$ git init
Initialized empty Git repository in .git/
$ git config user.name  "$DEBFULLNAME"
$ git config user.email "$DEBEMAIL"

This creates a new Git directory and sets the user name and email address that will be used in the commit message.

Importing Upstream Sources

It is quite common for packaging with Git that the upstream sources are stored in the repository. It is, however, not strictly necessary. But the costs are rather low and the benefit can be high, so this section will explain ways to import the upstream sources into you repository.

Using git-buildpackage and pristine-tar

There are two tools that will assist you in packaging with Git a lot: git-buildpackage and pristine-tar.

git-buildpackage can import upstream sources, create or import .diff.gzs and build a Debian package from Git repositories. It is similar in function to svn-buildpackage or other VCS-buildpackage tools.

pristine-tar is able to recreate bit-identical upstream tar-balls from the files stored under version control. It does so by creating small delta files, so that it is not necessary to store the whole tar-ball.

To import an upstream tar-ball into your repository, simply run:

$ git import-orig --pristine-tar ~/foo_1.0.orig.tar.gz
Upstream version is 1.0
Initial import of '/home/jdoe/foo_1.0.orig.tar.gz' ...
pristine-tar: committed foo_1.0.orig.tar.gz.delta to branch pristine-tar
Succesfully merged version 1.0 of /home/jdoe/foo_1.0.orig.tar.gz into .

After that, you will see two new branches, "upstream" and "pristine-tar":

$ git branch
* master
  pristine-tar
  upstream

The upstream branch holds your upstream sources as extracted from the tar-ball. The pristine-tar branch holds the delta files the pristine-tar created. Also, a tag has been created:

$ git tag -l
upstream/1.0

You can use git-import-orig for every new upstream tar-ball. It will extract the sources to the upstream branch and merge them back to the master branch.

Importing Upstream VCS Data

FIXME

Changes To The Upstream Sources

There are at least two methods for doing changes to upstream sources. One uses an integration branch, the other one uses a patch system. Both methods have it's benefits and drawbacks, so you have to decide which methods is best for your purpose.

Using An Integration Branch

By using this model, all changes to the upstream sources are made in independent branches and merged back into a special branch, the "integration" branch. This section tries to explain how this works.

When doing changes to the upstream sources, all logical changes should be stored in their own branch, a so-called "feature branch". The hardest part is giving it a reasonable name. If you want to fix a bug submitted to the BTS, you might want to call your branch "bug-nnn", where "nnn" is the bug number. You can also prefix Debian-specific changes with "deb/" to separate them from branches that contain patches which might be included upstream.

Note

You can also store each patch as one commit in a single feature branch, such as "upstream-patches". It is all up to you. Figure out what work-flow you like best.

After you thought of a name, you should branch from the latest upstream version. If you used git-import-orig, you can use the tags created by it:

$ git checkout -b bug-123456 upstream/1.0

You can now start fixing the bug inside this branch and commit the changes. For every change to the upstream sources, create a new branch and do your fixes in that until you're done. In the last step, it is time to merge the changes back to the integration branch.

FIXME: long-living or temporary integration branch? separate integration branch or master?

Using A Patch System

FIXME

Publishing Your Repository

This section will explain how to publish a repository in the Debian Islamic scope but should be easy to adopt for other teams or locations.

First, login to Alioth and create a new shared bare repository:

$ cd /git/debian-islamic/packages/
$ mkdir foo.git && cd foo.git
$ git --bare init --shared=all

You should also active the post-update-hook to allow checkouts via HTTP.

$ chmod 0775 hooks/post-update

Note

It is not recommended to use Git over HTTP but it may be handy for people behind a firewall.

You should also create a hook to send out commit emails to the commits mailing list. FIXME reference

There is a script called setup-repository.sh on Alioth that eases the creation of Git repository and creates the appropriate hooks.

The next step only applies if you do not use the "master" branch for storing you debian work. In this case, the HEAD reference in the repository has to be set to point to the branch you are going to push to the repository, or cloning will fail. Assuming your Debian-specific changes are stored in a branch called "debian", do:

$ echo 'ref: refs/heads/debian' > HEAD

The last steps need to be done on your local repository:

$ git remote add alioth ssh://user@git.debian.org/git/debian-islamic/packages/foo.git
git push --all alioth
git push --tags alioth

This tells you local repository about your remote repository and exports all of your branches and tags.

All these steps only need to be done once. After that, pushing your changes to the remote repository is all you need to do to publish them.