Debian Policy changes process

+ + +

Change Goals

+ + +

+The change should be technically correct, and consistent with the +rest of the policy document. This means no legislating the value of +Ï. This also means that the proposed solution be known to work; +iterative design processes do not belong in policy. +
+The change should not be too disruptive; if very many packages +become instantly buggy, then instead there should be a transition +plan. Exceptions should be rare (only if the current state is really +untenable), and probably blessed by the TC. +
+The change has to be reviewed in depth, in the open, where any one +may contribute; a publicly accessible, archived, open mailing list. +
+Proposal should be addressed in a timely fashion. +
+Any domain experts should be consulted, since not every policy +mailing list subscriber is an expert on everything, including policy +maintainers. +
+The goal is rough consensus on the change, which should not be hard +if the matter is technical. Technical issues where there is no +agreement should be referred to the TC; non-technical issues should +be referred to the whole developer body, and perhaps general +resolutions lie down that path. +
+Package maintainers whose packages may be impacted should have +access to policy change proposals, even if they do not subscribe to +policy mailing lists (policy gazette?). + +

+ +

Current Process

+ + +

+Each suggested change goes through different states. These states are +denoted through either usertags of the +debian-policy@packages.debian.org user or, for patch, pending, and +wontfix, regular tags. +

+Current list of bugs +

+The Policy delegates are responsible for managing the tags on bugs and +will update tags as new bugs are submitted or as activity happens on +bugs. All Debian Developers should feel free to add the seconded tag +as described below. Other tags should be changed with the coordination +of the Policy Team. +

+ +

State A: Issue raised

+ + +

+Detect need, like gaps/flaws in current policy, or a new rule should +be added. Any user or developer may start this step. There is a +decision point here, not all issues are in scope of policy. +TAG: issue +

+What needs to happen next: If this is in scope for Policy, discuss the +issue and possible solutions, moving to the discussion tag, or if the +matter is sufficiently clear, go directly to a proposal for how to +address it, moving to the proposal tag. If this is not in scope for +Policy, close the bug. +

+ +

State B: Discussion

+ + +

+Discuss remedy. Alternate proposals. Discussion guided by +delegates. There should be a clear time limit to this stage, but as +yet we have not set one. +TAG: discussion +

+What needs to happen next: Reach a conclusion and consensus in the +discussion and make a final proposal for what should be changed (if +anything), moving to the proposal tag. +

+ +

State D: Proposal

+ + +

+A final proposal has emerged from the discussion, and there is a rough +consensus on how to proceed to resolve the issue. +TAG: proposal +

+What needs to happen next: Provided that the rough consensus persists, +develop a patch against the current Policy document with specific +wording of the change. Often this is done in conjunction with the +proposal, in which case one may skip this step and move directly to +patch tag. +

+ +

State E: Wording proposed

+ + +

+A patch against the Policy document reflecting the consensus has been +created and is waiting for formal seconds. The standard patch tag is +used for this state, since it's essentially equivalent to the standard +meaning of that tag. +TAG: patch +

+What needs to happen next: The proposal needs to be reviewed and +seconded. Any Debian developer who agrees with the change and the +conclusion of rough consensus from the discussion should say so in the +bug log by seconding the proposal. +

+ +

State F: Seconded

+ + +

+The proposal is signed off on by N Debian Developers. To start with, +we're going with N=3, meaning that if three Debian Developers agree, +not just with the proposal but with the conclusion that it reflects +consensus and addresses the original issue – it is considered +eligible for inclusion in the next version of Policy. Since Policy is +partly a technical project governance method, one must be a Debian +Developer to formally second, although review and discussion is +welcome from anyone. Once this tag has been applied, the bug is +waiting for a Policy team member to apply the patch to the package +repository. +TAG: seconded +

+What needs to happen next: A Policy maintainer does the final review +and confirmation, and then applies the patch for the next Policy +release. +

+This tag is not used very much because normally a Policy maintainer +applies the patch and moves the proposal to the next state once enough +seconds are reached. +

+ +

State G: Accepted

+ + +

+Change accepted, will be in next upload. The standard pending tag is +used for this state since it matches the regular meaning of +pending. +TAG: pending +

+What needs to happen next: The bug is now in the waiting queue for the +next Policy release, and there's nothing left to do except for upload +a new version of Policy. +

+ +

State H: Reject

+ + +

+Rejected proposals. The standard wontfix is used for this +state. Normally, bugs in this state will not remain open; instead, a +Policy team member will close them with an explanation. The submitter +may then appeal to the tech-ctte if they so desire. Alternately, +issues appealed to the tech-ctte may remain open with this tag while +that appeal proceeds. +TAG: wontfix +

+We may use one of the following tags here, but to date we have only +used dubious and ctte. It's not clear whether we need more tags for +this tage. +

dubious: +Not a policy matter +
ctte: +Referred to the Technical Committee (tech-ctte) +
devel: +Referred to the developer body +
delegate: +Rejected by a Policy delegate +
obsolete: +The proposal timed out without a conclusion + +

+ +

What needs to happen next: The bug should be closed once a final +resolution is reached, or retagged to an appropriate state if that +final resolution reverses the decision to reject the proposal. +

+ +

Other Tags

+ + +

+All Policy bugs are additionally categorized by class of bug. +

+The normative tag is used for bugs that make normative changes to +Policy, meaning that the dictates of Policy will change in some +fashion as part of the resolution of the bug if the proposal is +accepted. The full process is followed for such bugs. +TAG: normative +

+The informative tag is used for bugs about wording issues, typos, +informative footnotes, or other changes that do not affect the formal +dictates of Policy, just the presentation. The same tags are used for +these bugs for convenience, but the Policy maintainers may make +informative changes without following the full process. Informative +bugs fall under their discretion. +TAG: informative +

+The packaging tag is used for bugs about the packaging and build +process of the debian-policy Debian package. These bugs do not follow +the normal process and will not have the other tags except for pending +and wontfix (used with their normal meanings). +TAG: packaging +

Author: Margarita Manterola, Clint Adams, Russ Allbery, and Manoj Srivastava +<srivasta@debian.org> +

Date: 2009-09-13 16:13:52 CDT

HTML generated by org-mode 6.30trans in emacs 23

Debian Policy

+ + +

Infrastructure

+ + +

+Website:: http://www.debian.org/doc/devel-manuals#policy +
+Mailing list:: debian-policy@lists.debian.org lists +
+Source Code:: +
- +git clone git://git.debian.org/git/dbnpolicy/policy.git +
- +Browser: http://git.debian.org/?p=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@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://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 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. +

+ +

Usual Roles

+ + +

+The Debian Policy team are official project delegates (see the 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: +

+Russ Allbery +
+Bill Allombert +
+Andrew McMillan +
+Manoj Srivastava +
+Colin Watson (cjwatson) + +

+ +

The special tasks of Policy delegates are: +

+Commit access to the Git repository and uploads of the debian-policy +package itself, which makes them responsible for debian-policy as a +package in Debian and for making final decisions about when a new +version is released and what bits go into it. +
+Rejecting proposals. Anyone can argue against a proposal, but only +Policy delegates can formally reject it. +
+Counting seconds and weighing objections to proposals to determine +whether the proposal has sufficient support to be included. + +

+ +

Everything else can be done by anyone, or any DD (depending on the +outcome of the discussion about seconding). We explicitly want any +Debian DD to review and second or object to proposals. The more +participation, the better. Many other people are active on the Policy +mailing list without being project delegates. +

+ +

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 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: +

+Debian Menu sub-policy +
+Debian Perl Policy +
+Debian MIME support sub-policy +
+Debconf Specification +
+Authoritative list of virtual package names + +

+ +

These documents are maintained using the Policy changes process, and +the current state of all change proposals is tracked using the +debian-policy BTS. +

+ +

Get involved

+ + +

+The best way to help is to review the current open bugs, pick a bug +that no one is currently shepherding (ask on +debian-policy@lists.debian.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 Policy changes process +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. +

+There are also some other, larger projects: +

+Policy is currently maintained in DebianDoc-SGML, which is no longer +very actively maintained and isn't a widely used or understood +format. The most logical replacement would be DocBook. However, +DocBook is a huge language with many tags and options, making it +rather overwhelming. We badly need someone with DocBook experience +to write a style guide specifying exactly which tags should be used +and what they should be used for so that we can limit ourselves to +an easy-to-understand and documented subset of the language. +
+Policy contains several appendices which are really documentation of +how parts of the dpkg system works rather than technical +Policy. Those appendices should be removed from the Policy document +and maintained elsewhere, probably as part of dpkg, and any Policy +statements in them moved into the main document. This project will +require reviewing the current contents of the appendices and feeding +the useful bits that aren't currently documented back to the dpkg +team as documentation patches. +
+Policy has grown organically over the years and suffers from +organizational issues because of it. It also doesn't make use of the +abilities that a current XML language might give us, such as being +able to extract useful portions of the document (all must +directives, for example). There has been quite a bit of discussion +of a new format that would allow for this, probably as part of +switching to DocBook, but as yet such a reorganization and reworking +has not been started. + +

+ +

If you want to work on any of these projects, please mail +debian-policy@lists.debian.org for more information. We'll be happy to +help you get started. +

+ +

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

+ +

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

+ + + + +

+ +

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

+ +

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

+ +

Setting release goals

+ + +

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

Author: Manoj Srivastava And Russ Allbery +<srivasta@debian.org> +

Date: 2009-10-05 00:20:29 CDT

HTML generated by org-mode 6.31trans in emacs 23

Debian Policy changes process

Change Goals

Current Process

State A: Issue raised

State B: Discussion

State D: Proposal

State E: Wording proposed

State F: Seconded

State G: Accepted

State H: Reject

Other Tags

Debian Policy

Infrastructure

Interacting with the team

Usual Roles

Task description

Get involved

Maintenance procedures

Repository layout

Managing a bug

Updating branches

Making a release

Setting release goals

Policy checklist for upgrading your packages

About the checklist

The checklist