README.txt

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