README.txt

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