Differences between revisions 21 and 22
Revision 21 as of 2013-01-09 13:02:55
Size: 13468
Comment: Update the list of maintained documents.
Revision 22 as of 2013-10-29 09:56:41
Size: 13452
Comment: Updated the list of Policy editors.
Deletions are marked like this. Additions are marked like this.
Line 43: Line 43:
The Debian Policy Editors are official project delegates (see the [[https://lists.debian.org/debian-devel-announce/2012/10/msg00006.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: The Debian Policy Editors are official project delegates (see the [[http://lists.debian.org/debian-devel-announce/2013/06/msg00004.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:
Line 47: Line 47:
 * [[CharlesPlessy|Charles Plessy]] (plessy)  * Jonathan Nieder (jrnieder)

Debian Policy


Interacting with the team

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. If you are taking responsibility for proposing wording and shepherding a proposal, please set yourself as the owner of that bug in the BTS.

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

Task description

The Debian Policy team is responsible for maintaining and coordinating updates to the Debian Policy Manual and all the other policy documents released as part of the debian-policy package.

The Debian Policy Editors:

  • Guide the work on the Debian Policy Manual and related documents as a collaborative process where developers review and second or object to proposals, usually on the debian-policy mailing list.

  • Count seconds and weight objections to proposals, to determine whether they have reached sufficient consensus to be included, and accept consensual proposals.
  • Reject or refer to the Technical Committee proposals that fail to reach consensus.
  • Commit changes to the version control system repository used to maintain the Debian Policy Manual and related documents.
  • Maintain the debian-policy package. As package maintainers, they have the last word on package content, releases, bug reports, etc.

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.

In addition to the main technical manual, the team currently also maintains:

These documents are maintained using the PolicyChangesProcess, 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 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.

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 AT lists DOT debian DOT 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, 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
    # If there are changes in master that make the branch not apply cleanly:
    : git checkout -b temp master; git merge bug12345-rra
    # If error;
     : git reset --hard HEAD;
    : git checkout bug12345-rra; git branch -D temp
    : 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 show-ref --heads | awk '{print $2}'`; do
        j=$(basename $i)
        if [ "$j" != "master" ]; then
            git checkout $j && git merge master
    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 PolicyChangesProcess (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.