Debian Policy

• Email contact:: mailto:debian-policy@lists.debian.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 Policy changes process.

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://anonscm.debian.org/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 master
git merge --no-commit <local-branch-name>
git reset --hard HEAD;
git checkout <local-branch-name>; 

# If there are changes in master that make the branch not apply cleanly, there
# should have been en error during the merge step above. If there was an
# error, merge the master branch into the local branch, fix the conflicts, and
# commit the new version of the local branch.
 : git merge master
# Edit files to remove conflict
 : git commit -s 

# Checkout the local branch, to create the patch to send to the policy
git checkout <local-branch-name>
dir=$(mktemp -d)
git format-patch -o $dir -s master
# check out the patches created in $dir
git send-email --from "you <your@email>"             \
	       --to debian-policy@lists.debian.org   \
	       $dir/

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

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

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.
• git pull master to make sure you have the latest version.
• Once the change has been approved by enough people, git merge the branch into master immediately after making the final commit adding the changelog entry to minimize conflicts.
• add the debian/changelog and upgrading-checklist.html changes, and commit to master.
• Push master out so other people may merge in their own bug branches without 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
# update your local master branch
git checkout master
git pull

git checkout master
git merge --no-commit bug12345-rra
git reset --hard HEAD;

# If there are changes in master that make the branch not apply cleanly, there
# should have been en error during the merge step above. If there was an
# error, merge the master branch into the local branch, fix the conflicts, and
# commit the new version of the local branch.
 : git checkout bug12345-rra
 : git merge master
# Edit files to remove conflict
 : git commit -s 

git checkout master
git merge bug12345-rra
# edit debian/changelog and upgrading-checklist.html
git add debian/changelog upgrading-checklist.html
git commit
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

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 show-ref --heads | awk '{print $2}'`; 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.

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), update the release date in upgrading-checklist.html, update Standards-Version in debian/control, 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.

Finally, announce the new Policy release on debian-devel-announce, including in the announcement the upgrading-checklist section for the new release.

Policy has a large bug backlog, and each bug against Policy tends to take considerable time and discussion to resolve. I've found it useful, when trying to find a place to start, to pick a manageable set of bugs and set as a target resolving them completely before the next Policy release. Resolving a bug means one of the following:

• Proposing new language to address the bug that's seconded and approved by the readers of the Policy list following the Policy changes process (or that's accepted by one of the Policy delegates if the change isn't normative; i.e., doesn't change the technical meaning of the document).
• Determining that the bug is not relevant to Policy and closing it.
• Determining that either there is no consensus that the bug indicates a problem, that the solutions that we can currently come up with are good solutions, or that Debian is ready for the change. These bugs are tagged wontfix and then closed after a while. A lot of Policy bugs fall into this category; just because it would be useful to have a policy in some area doesn't mean that we're ready to make one, and keeping the bugs open against Policy makes it difficult to tell what requires work. If the problem is worth writing a policy for, it will come up again later when hopefully the project consensus is more mature.

Anyone can pick bugs and work resolve them. The final determination to accept a wording change or reject a bug will be made by a Policy delegate, but if a patch is already written and seconded, or if a summary of why a bug is not ready to be acted on is already written, the work is much easier for the Policy delegate.

One of the best ways to help out is to pick one or two bugs (checking on the Policy list first), say that you'll make resolving them a goal for the next release, and guide the discussion until the bugs can reach one of the resolution states above.