README.org

   1 # -*- mode: org; fill-column: 78 -*-
   2 #+STARTUP: showall
   3 #+STARTUP: lognotedone lognotestate
   4 #+OPTIONS: H:4 toc:2
   5 #+TITLE:  Debian Policy
   6 #+AUTHOR: Manoj Srivastava And Russ Allbery
   7 #+EMAIL: srivasta@debian.org
   8 #+OPTIONS:   H:3 num:nil toc:nil \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:nil skip:t d:nil tags:not-in-toc
   9 #+LINK_HOME: http://wiki.debian.org/Teams/Policy
  10 #+LINK_UP: http://www.debian.org/
  11 #+LATEX_HEADER: \input{README-header.tex}
  12 * Infrastructure
  13
  14 + Website:: http://www.debian.org/doc/devel-manuals#policy
  15 + Mailing list:: debian-policy@lists.debian.org lists
  16 + Source Code::
  17   * git clone git://anonscm.debian.org/dbnpolicy/policy.git
  18   * Browser: http://anonscm.debian.org/gitweb/?p=dbnpolicy/policy.git
  19 + Unix group:: dbnpolicy
  20 + Alioth Project:: http://alioth.debian.org/projects/dbnpolicy (exists
  21   to manage the repository but not otherwise used)
  22
  23 ** Interacting with the team
  24
  25 + Email contact:: mailto:debian-policy@lists.debian.org
  26 + Request tracker:: http://bugs.debian.org/src:debian-policy
  27
  28 Debian Policy uses a formal procedure and a set of user tags to manage
  29 the lifecycle of change proposals. For definitions of those tags and
  30 proposal states and information about what the next step is for each
  31 phase, see [[./Process.org][Policy changes process]].
  32
  33 Once the wording for a change has been finalized, please send a patch
  34 against the current Git master branch to the bug report, if you're not
  35 familiar with Git, the following commands are the basic process:
  36
  37 #+BEGIN_SRC Sh
  38 git clone git://anonscm.debian.org/dbnpolicy/policy.git
  39 git checkout -b <local-branch-name>
  40
  41 # edit files, but don't make changes to upgrading-checklist or debian/changelog
  42 git add <files>
  43 git commit
  44 # repeat as necessary
  45
  46 # update your branch against the current master
  47 git checkout master
  48 git pull
  49
  50 git checkout master
  51 git merge --no-commit <local-branch-name>
  52 git reset --hard HEAD;
  53 git checkout <local-branch-name>;
  54
  55 # If there are changes in master that make the branch not apply cleanly, there
  56 # should have been en error during the merge step above. If there was an
  57 # error, merge the master branch into the local branch, fix the conflicts, and
  58 # commit the new version of the local branch.
  59  : git merge master
  60 # Edit files to remove conflict
  61  : git commit -s
  62
  63 # Checkout the local branch, to create the patch to send to the policy
  64 git checkout <local-branch-name>
  65 dir=$(mktemp -d)
  66 git format-patch -o $dir -s master
  67 # check out the patches created in $dir
  68 git send-email --from "you <your@email>"             \
  69                --to debian-policy@lists.debian.org   \
  70                $dir/
  71 #+END_SRC
  72
  73 <local-branch-name> is some convenient name designating your local
  74 changes. You may want to use some common prefix like local-. You can
  75 use git format-patch and git send-email if you want, but usually it's
  76 overkill.
  77
  78 * Usual Roles
  79
  80 The Debian Policy team are official project delegates (see the DPL
  81 delegation). All of the Policy team members do basically the same
  82 work: shepherd proposals, propose wording, and merge changes when
  83 consensus has been reached. The current delegates are:
  84
  85 + Andreas Barth (aba)
  86 + Bill Allombert (ballombe)
  87 + Jonathan Nieder (jrnieder)
  88 + Russ Allbery (rra)
  89
  90 * Task description
  91
  92 The Debian Policy team is responsible for maintaining and coordinating
  93 updates to the Debian Policy Manual and all the other policy documents
  94 released as part of the "debian-policy" package.
  95
  96 The Debian Policy Editors:
  97
  98 + Guide the work on the Debian Policy Manual and related documents as a
  99   collaborative process where developers review and second or object to
 100   proposals, usually on the debian-policy mailing list.
 101
 102 + Count seconds and weight objections to proposals, to determine whether
 103   they have reached sufficient consensus to be included, and accept
 104   consensual proposals.
 105
 106 + Reject or refer to the Technical Committee proposals that fail to
 107   reach consensus.
 108
 109 + Commit changes to the version control system repository used to
 110   maintain the Debian Policy Manual and related documents.
 111
 112 + Maintain the "debian-policy" package. As package maintainers, they
 113   have the last word on package content, releases, bug reports, etc.
 114
 115 Everything else can be done by anyone, or any DD (depending on the
 116 outcome of the discussion about seconding). We explicitly want any
 117 Debian DD to review and second or object to proposals. The more
 118 participation, the better. Many other people are active on the Policy
 119 mailing list without being project delegates.
 120
 121 In addition to the main technical manual, the team currently also maintains:
 122
 123 + [[http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/][Machine-readable debian/copyright format]]
 124 + [[http://www.debian.org/doc/packaging-manuals/menu-policy/][Debian Menu sub-policy]]
 125 + [[http://www.debian.org/doc/packaging-manuals/perl-policy/][Debian Perl Policy]]
 126 + [[http://www.debian.org/doc/packaging-manuals/debconf_specification.html][Debconf Specification]]
 127 + [[http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt][Authoritative list of virtual package names ]]
 128
 129 These documents are maintained using the [[./Process.org][Policy changes process]], and
 130 the current state of all change proposals is tracked using the
 131 [[http://bugs.debian.org/src:debian-policy][debian-policy BTS]].
 132
 133 * Get involved
 134
 135 The best way to help is to review the [[http://bugs.debian.org/src:debian-policy][current open bugs]], pick a bug
 136 that no one is currently shepherding (ask on
 137 [[mailto:debian-policy@lists.debian.org][debian-policy@lists.debian.org]] if you're not sure if a particular bug
 138 is being shepherded), and help it through the change process. This
 139 will involve guiding the discussion, seeking additional input
 140 (particularly from experts in the area being discussed), possibly
 141 raising the issue on other mailing lists, proposing or getting other
 142 people to propose specific wording changes, and writing diffs against
 143 the current Policy document. All of the steps of [[./Process.org][Policy changes process]]
 144 can be done by people other than Policy team members except
 145 the final acceptance steps and almost every change can be worked on
 146 independently, so there's a lot of opportunity for people to help.
 147
 148 There are also some other, larger projects:
 149
 150 + Policy is currently maintained in DebianDoc-SGML, which is no longer
 151   very actively maintained and isn't a widely used or understood
 152   format. The most logical replacement would be DocBook. However,
 153   DocBook is a huge language with many tags and options, making it
 154   rather overwhelming. We badly need someone with DocBook experience
 155   to write a style guide specifying exactly which tags should be used
 156   and what they should be used for so that we can limit ourselves to
 157   an easy-to-understand and documented subset of the language.
 158 + Policy contains several appendices which are really documentation of
 159   how parts of the dpkg system works rather than technical
 160   Policy. Those appendices should be removed from the Policy document
 161   and maintained elsewhere, probably as part of dpkg, and any Policy
 162   statements in them moved into the main document. This project will
 163   require reviewing the current contents of the appendices and feeding
 164   the useful bits that aren't currently documented back to the dpkg
 165   team as documentation patches.
 166 + Policy has grown organically over the years and suffers from
 167   organizational issues because of it. It also doesn't make use of the
 168   abilities that a current XML language might give us, such as being
 169   able to extract useful portions of the document (all *must*
 170   directives, for example). There has been quite a bit of discussion
 171   of a new format that would allow for this, probably as part of
 172   switching to DocBook, but as yet such a reorganization and reworking
 173   has not been started.
 174
 175 If you want to work on any of these projects, please mail
 176 [[mailto:debian-policy@lists.debian.org][debian-policy@lists.debian.org ]] for more information. We'll be happy to
 177 help you get started.
 178
 179 ** Maintenance procedures
 180
 181 ** Repository layout
 182
 183 The Git repository used for Debian Policy has the following branches:
 184
 185 +  master:: the current accepted changes that will be in the next release
 186 +  bug<number>-<user>:: changes addressing bug <number>, shepherded by <user>
 187 +  rra:: old history of Russ's arch repository, now frozen
 188 +  srivasta:: old history of Manoj's arch repository
 189
 190 ** Managing a bug
 191
 192 The process used by Policy team members to manage a bug, once there is
 193 proposed wording, is:
 194
 195 + Create a bug<number>-<user> branch for the bug, where <number> is
 196   the bug number in the BTS and <user> is a designator of the Policy
 197   team member who is shepherding the bug.
 198 + Commit wording changes in that branch until consensus is
 199   achieved. Do not modify debian/changelog or upgrading-checklist.html
 200   during this phase. Use the BTS to track who proposed the wording and
 201   who seconded it.
 202 + git pull master to make sure you have the latest version.
 203 + Once the change has been approved by enough people, git merge the
 204   branch into master immediately after making the final commit adding
 205   the changelog entry to minimize conflicts.
 206 + add the debian/changelog and upgrading-checklist.html changes, and
 207   commit to master.
 208 + Push master out so other people may merge in their own bug branches
 209   without conflicts.
 210 + Tag the bug as pending and remove other process tags.
 211 + Delete the now-merged branch.
 212
 213 The Git commands used for this workflow are:
 214 #+BEGIN_SRC Sh
 215 git checkout -b bug12345-rra master
 216 # edit files
 217 # git add files
 218 git commit
 219 git push origin bug12345-rra
 220 # iterate until good
 221 # update your local master branch
 222 git checkout master
 223 git pull
 224
 225 git checkout master
 226 git merge --no-commit bug12345-rra
 227 git reset --hard HEAD;
 228
 229 # If there are changes in master that make the branch not apply cleanly, there
 230 # should have been en error during the merge step above. If there was an
 231 # error, merge the master branch into the local branch, fix the conflicts, and
 232 # commit the new version of the local branch.
 233  : git checkout bug12345-rra
 234  : git merge master
 235 # Edit files to remove conflict
 236  : git commit -s
 237
 238 git checkout master
 239 git merge bug12345-rra
 240 # edit debian/changelog and upgrading-checklist.html
 241 git add debian/changelog upgrading-checklist.html
 242 git commit
 243 git push origin master
 244 git branch -d bug12345-rra
 245 git push origin :bug12345-rra
 246 #+END_SRC
 247
 248 For the debian/changelog entry, use the following format:
 249 #+BEGIN_EXAMPLE
 250   * <document>: <brief change description>
 251     Wording: <author of wording>
 252     Seconded: <seconder>
 253     Seconded: <seconder>
 254     Closes: <bug numbers>
 255 #+END_EXAMPLE
 256
 257 For example:
 258 #+BEGIN_EXAMPLE
 259   * Policy: better document version ranking and empty Debian revisions
 260     Wording: Russ Allbery <rra@debian.org>
 261     Seconded: Raphaël Hertzog <hertzog@debian.org>
 262     Seconded: Manoj Srivastava <srivasta@debian.org>
 263     Seconded: Guillem Jover <guillem@debian.org>
 264     Closes: #186700, #458910
 265 #+END_EXAMPLE
 266
 267 ** Updating branches
 268
 269 After commits to master have been pushed, either by you or by another
 270 Policy team member, you will generally want to update your working bug
 271 branches. The equivalent of the following commands should do that:
 272
 273 #+BEGIN_SRC Sh
 274 for i in `git show-ref --heads | awk '{print $2}'`; do
 275     j=$(basename $i)
 276     if [ "$j" != "master" ]; then
 277         git checkout $j && git merge master
 278     fi
 279 done
 280 git push --all origin
 281 #+END_SRC
 282
 283 assuming that you haven't packed the refs in your repository.
 284
 285 ** Making a release
 286
 287 For a final Policy release, change UNRELEASED to unstable in
 288 debian/changelog and update the timestamp to match the final release
 289 time (dch -r may be helpful for this), update the release date in
 290 upgrading-checklist.html, update Standards-Version in debian/control,
 291 and commit that change. Then do the final release build and make sure
 292 that it builds and installs.
 293
 294 Then, tag the repository and push the final changes to Alioth:
 295
 296 #+BEGIN_SRC Sh
 297 git tag -s v3.8.0.0
 298 git push origin
 299 git push --tags origin
 300 #+END_SRC
 301
 302 replacing the version number with the version of the release, of course.
 303
 304 Finally, announce the new Policy release on debian-devel-announce,
 305 including in the announcement the upgrading-checklist section for the
 306 new release.
 307
 308 ** Setting release goals
 309
 310 Policy has a large bug backlog, and each bug against Policy tends to
 311 take considerable time and discussion to resolve. I've found it
 312 useful, when trying to find a place to start, to pick a manageable set
 313 of bugs and set as a target resolving them completely before the next
 314 Policy release. Resolving a bug means one of the following:
 315
 316 + Proposing new language to address the bug that's seconded and approved by
 317   the readers of the Policy list following the [[./Progress.org][Policy changes process]] (or
 318   that's accepted by one of the Policy delegates if the change isn't
 319   normative; i.e., doesn't change the technical meaning of the document).
 320 + Determining that the bug is not relevant to Policy and closing it.
 321 + Determining that either there is no consensus that the bug indicates
 322   a problem, that the solutions that we can currently come up with are
 323   good solutions, or that Debian is ready for the change. These bugs
 324   are tagged wontfix and then closed after a while. A lot of Policy
 325   bugs fall into this category; just because it would be useful to
 326   have a policy in some area doesn't mean that we're ready to make
 327   one, and keeping the bugs open against Policy makes it difficult to
 328   tell what requires work. If the problem is worth writing a policy
 329   for, it will come up again later when hopefully the project
 330   consensus is more mature.
 331
 332 Anyone can pick bugs and work resolve them. The final determination to
 333 accept a wording change or reject a bug will be made by a Policy
 334 delegate, but if a patch is already written and seconded, or if a
 335 summary of why a bug is not ready to be acted on is already written,
 336 the work is much easier for the Policy delegate.
 337
 338 One of the best ways to help out is to pick one or two bugs (checking
 339 on the Policy list first), say that you'll make resolving them a goal
 340 for the next release, and guide the discussion until the bugs can
 341 reach one of the resolution states above.