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