README.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   3                "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml"
   5 lang="en" xml:lang="en">
   6 <head>
   7 <title>Debian Policy</title>
   8 <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
   9 <meta name="generator" content="Org-mode"/>
  10 <meta name="generated" content="2010-06-04 09:42:57 PDT"/>
  11 <meta name="author" content="Manoj Srivastava And Russ Allbery"/>
  12 <meta name="description" content=""/>
  13 <meta name="keywords" content=""/>
  14
  15 <style type="text/css">
  16   html { font-family: Times, serif; font-size: 12pt; }
  17   .title  { text-align: center; }
  18   p.verse { margin-left: 3% }
  19   pre {
  20         border: 1pt solid #AEBDCC;
  21         color: #000000;
  22         background-color: LightSlateGray;
  23         padding: 5pt;
  24         font-family: "Courier New", courier, monospace;
  25         font-size: 90%;
  26         overflow:auto;
  27   }
  28   dt { font-weight: bold; }
  29   div.figure { padding: 0.5em; }
  30   div.figure p { text-align: center; }
  31   .linenr { font-size:smaller }
  32   .code-highlighted {background-color:#ffff00;}
  33   .org-info-js_info-navigation { border-style:none; }
  34   #org-info-js_console-label { font-size:10px; font-weight:bold;
  35                                white-space:nowrap; }
  36   .org-info-js_search-highlight {background-color:#ffff00; color:#000000;
  37                                  font-weight:bold; }
  38
  39   body {
  40    color: black;
  41    background-color: white;
  42    font-family: Palatino, "Palatino Linotype", "Hoefler Text", "Times New Roman", Times, Georgia, Utopia, serif;
  43   }
  44   .org-agenda-date          { color: #87cefa;    }
  45   .org-agenda-structure     { color: #87cefa;    }
  46   .org-scheduled            { color: #98fb98;    }
  47   .org-scheduled-previously { color: #ff7f24;    }
  48   .org-scheduled-today      { color: #98fb98;    }
  49   .org-tag                  { font-weight: bold; }
  50   .org-todo                 {
  51     color: #ffc0cb;
  52     font-weight: bold;
  53   }
  54
  55   a:hover { text-decoration: underline; }
  56   .todo  { font-weight:bold; }
  57   .done { font-weight:bold; }
  58   .TODO { color:red; }
  59   .WAITING { color:orange; }
  60   .DONE { color:green; }
  61   .timestamp { color: grey }
  62   .timestamp-kwd { color: CadetBlue }
  63   .tag { background-color:lightblue; font-weight:normal }
  64   .target { background-color: lavender; }
  65 table {
  66         border-collapse: collapse; /*separate; */
  67         border: outset 3pt;
  68         border-spacing: 0pt;
  69         /* border-spacing: 5pt; */
  70         }
  71 table td             { vertical-align: top; border: 1px solid; }
  72 table th             { vertical-align: top; border: 2px solid; }
  73 </style>
  74 <script ="text/javascript" language="JavaScript" src="/styles/org-info.js"></script>
  75 <script type="text/javascript" language="JavaScript">
  76 /* <![CDATA[ */
  77 org_html_manager.set("LOCAL_TOC", 0);
  78 org_html_manager.set("VIEW_BUTTONS", 1);
  79 org_html_manager.set("VIEW", "info");
  80 org_html_manager.set("TOC", 1);
  81 org_html_manager.set("MOUSE_HINT", "underline"); // could be a background-color like #eeeeee
  82 org_html_manager.setup ();
  83 /* ]]> */
  84 </script>
  85
  86 <script type="text/javascript">
  87 <!--/*--><![CDATA[/*><!--*/
  88  function CodeHighlightOn(elem, id)
  89  {
  90    var target = document.getElementById(id);
  91    if(null != target) {
  92      elem.cacheClassElem = elem.className;
  93      elem.cacheClassTarget = target.className;
  94      target.className = "code-highlighted";
  95      elem.className   = "code-highlighted";
  96    }
  97  }
  98  function CodeHighlightOff(elem, id)
  99  {
 100    var target = document.getElementById(id);
 101    if(elem.cacheClassElem)
 102      elem.className = elem.cacheClassElem;
 103    if(elem.cacheClassTarget)
 104      target.className = elem.cacheClassTarget;
 105  }
 106 /*]]>*///-->
 107 </script>
 108 </head>
 109 <body>
 110 <div id="content">
 111 <div id="org-div-home-and-up" style="text-align:right;font-size:70%;white-space:nowrap;">
 112  <a accesskey="h" href="http://www.debian.org/"> UP </a>
 113  |
 114  <a accesskey="H" href="http://wiki.debian.org/Teams/Policy"> HOME </a>
 115 </div>
 116
 117 <h1 class="title">Debian Policy</h1>
 118
 119
 120 <div id="outline-container-1" class="outline-2">
 121 <h2 id="sec-1">Infrastructure </h2>
 122 <div class="outline-text-2" id="text-1">
 123
 124
 125 <ul>
 126 <li>
 127 Website:: <a href="http://www.debian.org/doc/devel-manuals#policy">http://www.debian.org/doc/devel-manuals#policy</a>
 128 </li>
 129 <li>
 130 Mailing list:: debian-policy@lists.debian.org lists
 131 </li>
 132 <li>
 133 Source Code::
 134 <ul>
 135 <li>
 136 git clone git://git.debian.org/git/dbnpolicy/policy.git
 137 </li>
 138 <li>
 139 Browser: <a href="http://git.debian.org/?p=dbnpolicy/policy.git">http://git.debian.org/?p=dbnpolicy/policy.git</a>
 140 </li>
 141 </ul>
 142 </li>
 143 <li>
 144 Unix group:: dbnpolicy
 145 </li>
 146 <li>
 147 Alioth Project:: <a href="http://alioth.debian.org/projects/dbnpolicy">http://alioth.debian.org/projects/dbnpolicy</a> (exists
 148 to manage the repository but not otherwise used)
 149
 150 </li>
 151 </ul>
 152
 153 </div>
 154
 155 <div id="outline-container-1_1" class="outline-3">
 156 <h3 id="sec-1_1">Interacting with the team </h3>
 157 <div class="outline-text-3" id="text-1_1">
 158
 159
 160 <ul>
 161 <li>
 162 Email contact:: <a href="mailto:debian-policy@lists.debian.org">mailto:debian-policy@lists.debian.org</a>
 163 </li>
 164 <li>
 165 Request tracker:: <a href="http://bugs.debian.org/src:debian-policy">http://bugs.debian.org/src:debian-policy</a>
 166
 167 </li>
 168 </ul>
 169
 170 <p>Debian Policy uses a formal procedure and a set of user tags to manage
 171 the lifecycle of change proposals. For definitions of those tags and
 172 proposal states and information about what the next step is for each
 173 phase, see <a href="./Process.html">Policy changes process</a>.
 174 </p>
 175 <p>
 176 Once the wording for a change has been finalized, please send a patch
 177 against the current Git master branch to the bug report, if you're not
 178 familiar with Git, the following commands are the basic process:
 179 </p>
 180
 181
 182
 183 <pre class="src src-Sh">git clone git://git.debian.org/git/dbnpolicy/policy.git
 184 git checkout -b &lt;local-branch-name&gt;
 185
 186 # edit files, but don't make changes to upgrading-checklist or debian/changelog
 187 git add &lt;files&gt;
 188 git commit
 189 # repeat as necessary
 190
 191 # update your branch against the current master
 192 git checkout master
 193 git pull
 194
 195 git checkout master
 196 git merge --no-commit &lt;local-branch-name&gt;
 197 git reset --hard HEAD;
 198 git checkout &lt;local-branch-name&gt;;
 199
 200 # If there are changes in master that make the branch not apply cleanly, there
 201 # should have been en error during the merge step above. If there was an
 202 # error, merge the master branch into the local branch, fix the conflicts, and
 203 # commit the new version of the local branch.
 204  : git merge master
 205 # Edit files to remove conflict
 206  : git commit -s
 207
 208 # Checkout the local branch, to create the patch to send to the policy
 209 git checkout &lt;local-branch-name&gt;
 210 dir=$(mktemp -d)
 211 git format-patch -o $dir -s master
 212 # check out the patches created in $dir
 213 git send-email --from <span style="font-style: italic;">"you &lt;<a href="mailto:your&#64;email">your&#64;email</a>&gt;"</span>             \
 214                --to debian-policy@lists.debian.org   \
 215                $dir/
 216 </pre>
 217
 218
 219
 220 <p>
 221 &lt;local-branch-name&gt; is some convenient name designating your local
 222 changes. You may want to use some common prefix like local-. You can
 223 use git format-patch and git send-email if you want, but usually it's
 224 overkill.
 225 </p>
 226 </div>
 227 </div>
 228
 229 </div>
 230
 231 <div id="outline-container-2" class="outline-2">
 232 <h2 id="sec-2">Usual Roles </h2>
 233 <div class="outline-text-2" id="text-2">
 234
 235
 236 <p>
 237 The Debian Policy team are official project delegates (see the DPL
 238 delegation). All of the Policy team members do basically the same
 239 work: shepherd proposals, propose wording, and merge changes when
 240 consensus has been reached. The current delegates are:
 241 </p>
 242 <ul>
 243 <li>
 244 Russ Allbery
 245 </li>
 246 <li>
 247 Bill Allombert
 248 </li>
 249 <li>
 250 Andrew McMillan
 251 </li>
 252 <li>
 253 Manoj Srivastava
 254 </li>
 255 <li>
 256 Colin Watson (cjwatson)
 257
 258 </li>
 259 </ul>
 260
 261 <p>The special tasks of Policy delegates are:
 262 </p>
 263 <ul>
 264 <li>
 265 Commit access to the Git repository and uploads of the debian-policy
 266 package itself, which makes them responsible for debian-policy as a
 267 package in Debian and for making final decisions about when a new
 268 version is released and what bits go into it.
 269 </li>
 270 <li>
 271 Rejecting proposals. Anyone can argue against a proposal, but only
 272 Policy delegates can formally reject it.
 273 </li>
 274 <li>
 275 Counting seconds and weighing objections to proposals to determine
 276 whether the proposal has sufficient support to be included.
 277
 278 </li>
 279 </ul>
 280
 281 <p>Everything else can be done by anyone, or any DD (depending on the
 282 outcome of the discussion about seconding). We explicitly want any
 283 Debian DD to review and second or object to proposals. The more
 284 participation, the better. Many other people are active on the Policy
 285 mailing list without being project delegates.
 286 </p>
 287 </div>
 288
 289 </div>
 290
 291 <div id="outline-container-3" class="outline-2">
 292 <h2 id="sec-3">Task description </h2>
 293 <div class="outline-text-2" id="text-3">
 294
 295
 296 <p>
 297 The Debian Policy team is responsible for maintaining and coordinating
 298 updates to the technical Policy manuals for the project. The primary
 299 output of the team is the Debian Policy Manual and the assorted
 300 subpolicies, released as the debian-policy Debian package and also
 301 published at <a href="http://www.debian.org/doc/">http://www.debian.org/doc/</a>.
 302 </p>
 303 <p>
 304 In addition to the main technical manual, the team currently also maintains:
 305 </p>
 306 <ul>
 307 <li>
 308 <a href="http://www.debian.org/doc/packaging-manuals/menu-policy/">Debian Menu sub-policy</a>
 309 </li>
 310 <li>
 311 <a href="http://www.debian.org/doc/packaging-manuals/perl-policy/">Debian Perl Policy</a>
 312 </li>
 313 <li>
 314 <a href="http://www.debian.org/doc/packaging-manuals/mime-policy/">Debian MIME support sub-policy</a>
 315 </li>
 316 <li>
 317 <a href="http://www.debian.org/doc/packaging-manuals/debconf_specification.html">Debconf Specification</a>
 318 </li>
 319 <li>
 320 <a href="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt">Authoritative list of virtual package names </a>
 321
 322 </li>
 323 </ul>
 324
 325 <p>These documents are maintained using the <a href="./Process.html">Policy changes process</a>, and
 326 the current state of all change proposals is tracked using the
 327 <a href="http://bugs.debian.org/src:debian-policy">debian-policy BTS</a>.
 328 </p>
 329 </div>
 330
 331 </div>
 332
 333 <div id="outline-container-4" class="outline-2">
 334 <h2 id="sec-4">Get involved </h2>
 335 <div class="outline-text-2" id="text-4">
 336
 337
 338 <p>
 339 The best way to help is to review the <a href="http://bugs.debian.org/src:debian-policy">current open bugs</a>, pick a bug
 340 that no one is currently shepherding (ask on
 341 <a href="mailto:debian-policy@lists.debian.org">debian-policy@lists.debian.org</a> if you're not sure if a particular bug
 342 is being shepherded), and help it through the change process. This
 343 will involve guiding the discussion, seeking additional input
 344 (particularly from experts in the area being discussed), possibly
 345 raising the issue on other mailing lists, proposing or getting other
 346 people to propose specific wording changes, and writing diffs against
 347 the current Policy document. All of the steps of <a href="./Process.html">Policy changes process</a>
 348 can be done by people other than Policy team members except
 349 the final acceptance steps and almost every change can be worked on
 350 independently, so there's a lot of opportunity for people to help.
 351 </p>
 352 <p>
 353 There are also some other, larger projects:
 354 </p>
 355 <ul>
 356 <li>
 357 Policy is currently maintained in DebianDoc-SGML, which is no longer
 358 very actively maintained and isn't a widely used or understood
 359 format. The most logical replacement would be DocBook. However,
 360 DocBook is a huge language with many tags and options, making it
 361 rather overwhelming. We badly need someone with DocBook experience
 362 to write a style guide specifying exactly which tags should be used
 363 and what they should be used for so that we can limit ourselves to
 364 an easy-to-understand and documented subset of the language.
 365 </li>
 366 <li>
 367 Policy contains several appendices which are really documentation of
 368 how parts of the dpkg system works rather than technical
 369 Policy. Those appendices should be removed from the Policy document
 370 and maintained elsewhere, probably as part of dpkg, and any Policy
 371 statements in them moved into the main document. This project will
 372 require reviewing the current contents of the appendices and feeding
 373 the useful bits that aren't currently documented back to the dpkg
 374 team as documentation patches.
 375 </li>
 376 <li>
 377 Policy has grown organically over the years and suffers from
 378 organizational issues because of it. It also doesn't make use of the
 379 abilities that a current XML language might give us, such as being
 380 able to extract useful portions of the document (all <b>must</b>
 381 directives, for example). There has been quite a bit of discussion
 382 of a new format that would allow for this, probably as part of
 383 switching to DocBook, but as yet such a reorganization and reworking
 384 has not been started.
 385
 386 </li>
 387 </ul>
 388
 389 <p>If you want to work on any of these projects, please mail
 390 <a href="mailto:debian-policy@lists.debian.org">debian-policy@lists.debian.org </a> for more information. We'll be happy to
 391 help you get started.
 392 </p>
 393
 394 </div>
 395
 396 <div id="outline-container-4_1" class="outline-3">
 397 <h3 id="sec-4_1">Maintenance procedures </h3>
 398 <div class="outline-text-3" id="text-4_1">
 399
 400
 401 </div>
 402
 403 </div>
 404
 405 <div id="outline-container-4_2" class="outline-3">
 406 <h3 id="sec-4_2">Repository layout </h3>
 407 <div class="outline-text-3" id="text-4_2">
 408
 409
 410 <p>
 411 The Git repository used for Debian Policy has the following branches:
 412 </p>
 413 <ul>
 414 <li>
 415  master:: the current accepted changes that will be in the next release
 416 </li>
 417 <li>
 418  bug&lt;number&gt;-&lt;user&gt;:: changes addressing bug &lt;number&gt;, shepherded by &lt;user&gt;
 419 </li>
 420 <li>
 421  rra:: old history of Russ's arch repository, now frozen
 422 </li>
 423 <li>
 424  srivasta:: old history of Manoj's arch repository
 425
 426 </li>
 427 </ul>
 428 </div>
 429
 430 </div>
 431
 432 <div id="outline-container-4_3" class="outline-3">
 433 <h3 id="sec-4_3">Managing a bug </h3>
 434 <div class="outline-text-3" id="text-4_3">
 435
 436
 437 <p>
 438 The process used by Policy team members to manage a bug, once there is
 439 proposed wording, is:
 440 </p>
 441 <ul>
 442 <li>
 443 Create a bug&lt;number&gt;-&lt;user&gt; branch for the bug, where &lt;number&gt; is
 444 the bug number in the BTS and &lt;user&gt; is a designator of the Policy
 445 team member who is shepherding the bug.
 446 </li>
 447 <li>
 448 Commit wording changes in that branch until consensus is
 449 achieved. Do not modify debian/changelog or upgrading-checklist.html
 450 during this phase. Use the BTS to track who proposed the wording and
 451 who seconded it.
 452 </li>
 453 <li>
 454 git pull master to make sure you have the latest version.
 455 </li>
 456 <li>
 457 Once the change has been approved by enough people, git merge the
 458 branch into master immediately after making the final commit adding
 459 the changelog entry to minimize conflicts.
 460 </li>
 461 <li>
 462 add the debian/changelog and upgrading-checklist.html changes, and
 463 commit to master.
 464 </li>
 465 <li>
 466 Push master out so other people may merge in their own bug branches
 467 without conflicts.
 468 </li>
 469 <li>
 470 Tag the bug as pending and remove other process tags.
 471 </li>
 472 <li>
 473 Delete the now-merged branch.
 474
 475 </li>
 476 </ul>
 477
 478 <p>The Git commands used for this workflow are:
 479 </p>
 480
 481
 482 <pre class="src src-Sh">git checkout -b bug12345-rra master
 483 # edit files
 484 # git add files
 485 git commit
 486 git push origin bug12345-rra
 487 # iterate until good
 488 # update your local master branch
 489 git checkout master
 490 git pull
 491
 492 git checkout master
 493 git merge --no-commit bug12345-rra
 494 git reset --hard HEAD;
 495
 496 # If there are changes in master that make the branch not apply cleanly, there
 497 # should have been en error during the merge step above. If there was an
 498 # error, merge the master branch into the local branch, fix the conflicts, and
 499 # commit the new version of the local branch.
 500  : git checkout bug12345-rra
 501  : git merge master
 502 # Edit files to remove conflict
 503  : git commit -s
 504
 505 git checkout master
 506 git merge bug12345-rra
 507 # edit debian/changelog and upgrading-checklist.html
 508 git add debian/changelog upgrading-checklist.html
 509 git commit
 510 git push origin master
 511 git branch -d bug12345-rra
 512 git push origin :bug12345-rra
 513 </pre>
 514
 515
 516
 517 <p>
 518 For the debian/changelog entry, use the following format:
 519 </p>
 520
 521
 522 <pre class="example">* &lt;document&gt;: &lt;brief change description&gt;
 523   Wording: &lt;author of wording&gt;
 524   Seconded: &lt;seconder&gt;
 525   Seconded: &lt;seconder&gt;
 526   Closes: &lt;bug numbers&gt;
 527 </pre>
 528
 529
 530
 531 <p>
 532 For example:
 533 </p>
 534
 535
 536 <pre class="example">* Policy: better document version ranking and empty Debian revisions
 537   Wording: Russ Allbery &lt;rra@debian.org&gt;
 538   Seconded: Raphaël Hertzog &lt;hertzog@debian.org&gt;
 539   Seconded: Manoj Srivastava &lt;srivasta@debian.org&gt;
 540   Seconded: Guillem Jover &lt;guillem@debian.org&gt;
 541   Closes: #186700, #458910
 542 </pre>
 543
 544
 545
 546 </div>
 547
 548 </div>
 549
 550 <div id="outline-container-4_4" class="outline-3">
 551 <h3 id="sec-4_4">Updating branches </h3>
 552 <div class="outline-text-3" id="text-4_4">
 553
 554
 555 <p>
 556 After commits to master have been pushed, either by you or by another
 557 Policy team member, you will generally want to update your working bug
 558 branches. The equivalent of the following commands should do that:
 559 </p>
 560
 561
 562
 563 <pre class="src src-Sh">for i in `git show-ref --heads | awk '{print $2}'`; do
 564     j=$(basename $i)
 565     if [ <span style="font-style: italic;">"$j"</span> != <span style="font-style: italic;">"master"</span> ]; then
 566         git checkout $j &amp;&amp; git merge master
 567     fi
 568 done
 569 git push --all origin
 570 </pre>
 571
 572
 573
 574 <p>
 575 assuming that you haven't packed the refs in your repository.
 576 </p>
 577 </div>
 578
 579 </div>
 580
 581 <div id="outline-container-4_5" class="outline-3">
 582 <h3 id="sec-4_5">Making a release </h3>
 583 <div class="outline-text-3" id="text-4_5">
 584
 585
 586 <p>
 587 For a final Policy release, change UNRELEASED to unstable in
 588 debian/changelog and update the timestamp to match the final release
 589 time (dch -r may be helpful for this), update the release date in
 590 upgrading-checklist.html, update Standards-Version in debian/control,
 591 and commit that change. Then do the final release build and make sure
 592 that it builds and installs.
 593 </p>
 594 <p>
 595 Then, tag the repository and push the final changes to Alioth:
 596 </p>
 597
 598
 599
 600 <pre class="src src-Sh">git tag -s v3.8.0.0
 601 git push origin
 602 git push --tags origin
 603 </pre>
 604
 605
 606
 607 <p>
 608 replacing the version number with the version of the release, of course.
 609 </p>
 610 <p>
 611 Finally, announce the new Policy release on debian-devel-announce,
 612 including in the announcement the upgrading-checklist section for the
 613 new release.
 614 </p>
 615 </div>
 616
 617 </div>
 618
 619 <div id="outline-container-4_6" class="outline-3">
 620 <h3 id="sec-4_6">Setting release goals </h3>
 621 <div class="outline-text-3" id="text-4_6">
 622
 623
 624 <p>
 625 Policy has a large bug backlog, and each bug against Policy tends to
 626 take considerable time and discussion to resolve. I've found it
 627 useful, when trying to find a place to start, to pick a manageable set
 628 of bugs and set as a target resolving them completely before the next
 629 Policy release. Resolving a bug means one of the following:
 630 </p>
 631 <ul>
 632 <li>
 633 Proposing new language to address the bug that's seconded and approved by
 634 the readers of the Policy list following the <a href="./Progress.html">Policy changes process</a> (or
 635 that's accepted by one of the Policy delegates if the change isn't
 636 normative; i.e., doesn't change the technical meaning of the document).
 637 </li>
 638 <li>
 639 Determining that the bug is not relevant to Policy and closing it.
 640 </li>
 641 <li>
 642 Determining that either there is no consensus that the bug indicates
 643 a problem, that the solutions that we can currently come up with are
 644 good solutions, or that Debian is ready for the change. These bugs
 645 are tagged wontfix and then closed after a while. A lot of Policy
 646 bugs fall into this category; just because it would be useful to
 647 have a policy in some area doesn't mean that we're ready to make
 648 one, and keeping the bugs open against Policy makes it difficult to
 649 tell what requires work. If the problem is worth writing a policy
 650 for, it will come up again later when hopefully the project
 651 consensus is more mature.
 652
 653 </li>
 654 </ul>
 655
 656 <p>Anyone can pick bugs and work resolve them. The final determination to
 657 accept a wording change or reject a bug will be made by a Policy
 658 delegate, but if a patch is already written and seconded, or if a
 659 summary of why a bug is not ready to be acted on is already written,
 660 the work is much easier for the Policy delegate.
 661 </p>
 662 <p>
 663 One of the best ways to help out is to pick one or two bugs (checking
 664 on the Policy list first), say that you'll make resolving them a goal
 665 for the next release, and guide the discussion until the bugs can
 666 reach one of the resolution states above.
 667 </p></div>
 668 </div>
 669 </div>
 670 <div id="postamble">
 671 <p class="author"> Author: Manoj Srivastava And Russ Allbery
 672 </p>
 673 <p class="date"> Date: 2010-06-04 09:42:57 PDT</p>
 674 <p class="creator">HTML generated by org-mode 6.36c in emacs 23</p>
 675 </div>
 676 </div>
 677 </body>
 678 </html>