Debian Policy
Infrastructure
Mailing list: ?MailTo(debian-policy AT lists DOT debian DOT org) [http://lists.debian.org/debian-policy/ lists]
Source Code:
git clone git://git.debian.org/git/dbnpolicy/policy.git
Unix group: dbnpolicy
Alioth Project: http://alioth.debian.org/projects/dbnpolicy (exists to manage the repository but not otherwise used)
Interacting with the team
Email contact: ?MailTo(debian-policy AT lists DOT debian DOT org)
Request tracker: http://bugs.debian.org/src:debian-policy
Debian Policy uses a formal procedure and a set of user tags to manage the lifecycle of change proposals. For definitions of those tags and proposal states and information about what the next step is for each phase, see PolicyChangesProcess.
Once the wording for a change has been finalized, please send a patch against the current Git master branch to the bug report, if you're not familiar with Git, the following commands are the basic process:
git clone git://git.debian.org/git/dbnpolicy/policy.git git checkout -b <local-branch-name> # edit files, but don't make changes to upgrading-checklist or debian/changelog git add <files> git commit # repeat as necessary # update your branch against the current master git checkout master git pull git checkout <local-branch-name> git merge master # generate a diff to send to the list git checkout master git diff master..<local-branch-name>
<local-branch-name> is some convenient name designating your local changes. You may want to use some common prefix like local-. You can use git format-patch and git send-email if you want, but usually it's overkill.
Usual roles
The Debian Policy team are official project delegates (see the [http://lists.debian.org/debian-project/2006/11/msg00007.html DPL delegation]). All of the Policy team members do basically the same work: shepherd proposals, propose wording, and merge changes when consensus has been reached. The current delegates are:
[wiki:RussAllbery Russ Allbery] (rra)
- [wiki:Manoj_Srivastava Manoj Srivastava]
- Junichi Uekawa (not currently active)
- Andreas Barth (not currently active)
- [wiki:Marga Margarita Manterola] (not currently active)
Task description
The Debian Policy team is responsible for maintaining and coordinating updates to the technical Policy manuals for the project. The primary output of the team is the Debian Policy Manual and the assorted subpolicies, released as the [http://packages.qa.debian.org/d/debian-policy.html debian-policy Debian package] and also published at [http://www.debian.org/doc/].
In addition to the main technical manual, the team currently also maintains:
[http://www.debian.org/doc/packaging-manuals/menu-policy/ Debian Menu sub-policy]
[http://www.debian.org/doc/packaging-manuals/perl-policy/ Debian Perl Policy]
[http://www.debian.org/doc/packaging-manuals/mime-policy/ Debian MIME support sub-policy]
[http://www.debian.org/doc/packaging-manuals/debconf_specification.html Debconf Specification]
[http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt Authoritative list of virtual package names]
These documents are maintained using the PolicyChangesProcess, and the current state of all change proposals is tracked using the [http://bugs.debian.org/src:debian-policy debian-policy BTS].
Get involved
The best way to help is to review the [http://bugs.debian.org/src:debian-policy current open bugs], pick a bug that no one is currently shepherding (ask on ?MailTo(debian-policy AT lists DOT debian DOT org) if you're not sure if a particular bug is being shepherded), and help it through the change process. This will involve guiding the discussion, seeking additional input (particularly from experts in the area being discussed), possibly raising the issue on other mailing lists, proposing or getting other people to propose specific wording changes, and writing diffs against the current Policy document. All of the steps of PolicyChangesProcess can be done by people other than Policy team members except the final acceptance steps and almost every change can be worked on independently, so there's a lot of opportunity for people to help.
If you want to tackle an even larger project, Manoj is working on a rewrite of the current Policy manual, probably in DocBook, which will involve reviewing the current Policy document, breaking it into separate rules, and rewriting the text in a more formal structure. This project is only just starting. Contact Manoj or ?MailTo(debian-policy AT lists DOT debian DOT org) for more information.
Maintenance procedures
Repository layout
The Git repository used for Debian Policy has the following branches:
master: the current accepted changes that will be in the next release
bug<number>-<user>: changes addressing bug <number>, shepherded by <user>
rra: old history of Russ's arch repository, now frozen
srivasta: old history of Manoj's arch repository, now frozen
Managing a bug
The process used by Policy team members to manage a bug, once there is proposed wording, is:
Create a bug<number>-<user> branch for the bug, where <number> is the bug number in the BTS and <user> is a designator of the Policy team member who is shepherding the bug.
- Commit wording changes in that branch until consensus is achieved. Do not modify debian/changelog or upgrading-checklist.html during this phase. Use the BTS to track who proposed the wording and who seconded it.
- Once the change has been approved by enough people, add the debian/changelog and upgrading-checklist.html changes as the final changes in the branch. git merge master onto the branch first if any changes have been made on master since the last merge.
- git merge the branch into master immediately after making the final commit adding the changelog entry to minimize conflicts.
- Tag the bug as pending and remove other process tags.
- Delete the now-merged branch.
The Git commands used for this workflow are:
git checkout -b bug12345-rra master # edit files # git add files git commit git push origin bug12345-rra # iterate until good git merge master # edit debian/changelog and upgrading-checklist.html git add debian/changelog upgrading-checklist.html git commit git checkout master git merge bug12345-rra git push origin master git branch -d bug12345-rra git push origin :bug12345-rra
For the debian/changelog entry, use the following format:
* <document>: <brief change description> Wording: <author of wording> Seconded: <seconder> Seconded: <seconder> Closes: <bug numbers>
For example:
* Policy: better document version ranking and empty Debian revisions Wording: Russ Allbery <rra@debian.org> Seconded: Raphaƫl Hertzog <hertzog@debian.org> Seconded: Manoj Srivastava <srivasta@debian.org> Seconded: Guillem Jover <guillem@debian.org> Closes: #186700, #458910
Updating branches
After commits to master have been pushed, either by you or by another Policy team member, you will generally want to update your working bug branches. The equivalent of the following commands should do that:
for i in .git/refs/heads/*; do j=$(basename $i) if [ "$j" != "master" ]; then git checkout $j && git merge master fi done git push --all origin
assuming that you haven't packed the refs in your repository.
Making a release
For a final Policy release, change UNRELEASED to unstable in debian/changelog and update the timestamp to match the final release time (dch -r may be helpful for this) and commit that change. Then do the final release build and make sure that it builds and installs.
Then, tag the repository and push the final changes to Alioth:
git tag -s v3.8.0.0 git push origin git push --tags origin
replacing the version number with the version of the release, of course.