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