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