- UP - | - HOME -

- -

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 C: 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 D: 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 E: 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 F: 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 G: 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 -

Date: 2010-06-04 09:41:24 PDT

HTML generated by org-mode 6.36c in emacs 23

- UP - | - HOME -

- -

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 -

Date: 2010-06-04 09:42:57 PDT

HTML generated by org-mode 6.36c in emacs 23