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