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-15 15:48:45 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 # If there are changes in master that make the branch not apply cleanly:
 202  : git checkout -b temp master; git merge &lt;local-branch-name&gt;
 203 # If error, reset temp, merge master into local; else skip these three lines
 204  : git reset --hard HEAD;
 205  : git checkout &lt;local-branch-name&gt;;
 206  : git merge master
 207 # get rid of the temp branch:
 208  : git branch -D temp
 209
 210 # Checkout the local branch, to create the patch to send to the policy
 211 git checkout &lt;local-branch-name&gt;
 212 dir=$(mktemp -d)
 213 git format-patch -o $dir -s master
 214 # check out the patches created in $dir
 215 git send-email --from <span style="font-style: italic;">"you &lt;<a href="mailto:your&#64;email">your&#64;email</a>&gt;"</span>             \
 216                --to debian-policy@lists.debian.org   \
 217                $dir/
 218 </pre>
 219
 220
 221
 222
 223 <p>
 224 &lt;local-branch-name&gt; is some convenient name designating your local
 225 changes. You may want to use some common prefix like local-. You can
 226 use git format-patch and git send-email if you want, but usually it's
 227 overkill.
 228 </p>
 229 </div>
 230 </div>
 231
 232 </div>
 233
 234 <div id="outline-container-2" class="outline-2">
 235 <h2 id="sec-2">Usual Roles </h2>
 236 <div class="outline-text-2" id="text-2">
 237
 238
 239 <p>
 240 The Debian Policy team are official project delegates (see the DPL
 241 delegation). All of the Policy team members do basically the same
 242 work: shepherd proposals, propose wording, and merge changes when
 243 consensus has been reached. The current delegates are:
 244 </p>
 245 <ul>
 246 <li>
 247 Russ Allbery
 248 </li>
 249 <li>
 250 Bill Allombert
 251 </li>
 252 <li>
 253 Andrew McMillan
 254 </li>
 255 <li>
 256 Manoj Srivastava
 257 </li>
 258 <li>
 259 Colin Watson (cjwatson)
 260
 261 </li>
 262 </ul>
 263
 264 <p>The special tasks of Policy delegates are:
 265 </p>
 266 <ul>
 267 <li>
 268 Commit access to the Git repository and uploads of the debian-policy
 269 package itself, which makes them responsible for debian-policy as a
 270 package in Debian and for making final decisions about when a new
 271 version is released and what bits go into it.
 272 </li>
 273 <li>
 274 Rejecting proposals. Anyone can argue against a proposal, but only
 275 Policy delegates can formally reject it.
 276 </li>
 277 <li>
 278 Counting seconds and weighing objections to proposals to determine
 279 whether the proposal has sufficient support to be included.
 280
 281 </li>
 282 </ul>
 283
 284 <p>Everything else can be done by anyone, or any DD (depending on the
 285 outcome of the discussion about seconding). We explicitly want any
 286 Debian DD to review and second or object to proposals. The more
 287 participation, the better. Many other people are active on the Policy
 288 mailing list without being project delegates.
 289 </p>
 290 </div>
 291
 292 </div>
 293
 294 <div id="outline-container-3" class="outline-2">
 295 <h2 id="sec-3">Task description </h2>
 296 <div class="outline-text-2" id="text-3">
 297
 298
 299 <p>
 300 The Debian Policy team is responsible for maintaining and coordinating
 301 updates to the technical Policy manuals for the project. The primary
 302 output of the team is the Debian Policy Manual and the assorted
 303 subpolicies, released as the debian-policy Debian package and also
 304 published at <a href="http://www.debian.org/doc/">http://www.debian.org/doc/</a>.
 305 </p>
 306 <p>
 307 In addition to the main technical manual, the team currently also maintains:
 308 </p>
 309 <ul>
 310 <li>
 311 <a href="http://www.debian.org/doc/packaging-manuals/menu-policy/">Debian Menu sub-policy</a>
 312 </li>
 313 <li>
 314 <a href="http://www.debian.org/doc/packaging-manuals/perl-policy/">Debian Perl Policy</a>
 315 </li>
 316 <li>
 317 <a href="http://www.debian.org/doc/packaging-manuals/mime-policy/">Debian MIME support sub-policy</a>
 318 </li>
 319 <li>
 320 <a href="http://www.debian.org/doc/packaging-manuals/debconf_specification.html">Debconf Specification</a>
 321 </li>
 322 <li>
 323 <a href="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt">Authoritative list of virtual package names </a>
 324
 325 </li>
 326 </ul>
 327
 328 <p>These documents are maintained using the <a href="./Process.html">Policy changes process</a>, and
 329 the current state of all change proposals is tracked using the
 330 <a href="http://bugs.debian.org/src:debian-policy">debian-policy BTS</a>.
 331 </p>
 332 </div>
 333
 334 </div>
 335
 336 <div id="outline-container-4" class="outline-2">
 337 <h2 id="sec-4">Get involved </h2>
 338 <div class="outline-text-2" id="text-4">
 339
 340
 341 <p>
 342 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
 343 that no one is currently shepherding (ask on
 344 <a href="mailto:debian-policy@lists.debian.org">debian-policy@lists.debian.org</a> if you're not sure if a particular bug
 345 is being shepherded), and help it through the change process. This
 346 will involve guiding the discussion, seeking additional input
 347 (particularly from experts in the area being discussed), possibly
 348 raising the issue on other mailing lists, proposing or getting other
 349 people to propose specific wording changes, and writing diffs against
 350 the current Policy document. All of the steps of <a href="./Process.html">Policy changes process</a>
 351 can be done by people other than Policy team members except
 352 the final acceptance steps and almost every change can be worked on
 353 independently, so there's a lot of opportunity for people to help.
 354 </p>
 355 <p>
 356 There are also some other, larger projects:
 357 </p>
 358 <ul>
 359 <li>
 360 Policy is currently maintained in DebianDoc-SGML, which is no longer
 361 very actively maintained and isn't a widely used or understood
 362 format. The most logical replacement would be DocBook. However,
 363 DocBook is a huge language with many tags and options, making it
 364 rather overwhelming. We badly need someone with DocBook experience
 365 to write a style guide specifying exactly which tags should be used
 366 and what they should be used for so that we can limit ourselves to
 367 an easy-to-understand and documented subset of the language.
 368 </li>
 369 <li>
 370 Policy contains several appendices which are really documentation of
 371 how parts of the dpkg system works rather than technical
 372 Policy. Those appendices should be removed from the Policy document
 373 and maintained elsewhere, probably as part of dpkg, and any Policy
 374 statements in them moved into the main document. This project will
 375 require reviewing the current contents of the appendices and feeding
 376 the useful bits that aren't currently documented back to the dpkg
 377 team as documentation patches.
 378 </li>
 379 <li>
 380 Policy has grown organically over the years and suffers from
 381 organizational issues because of it. It also doesn't make use of the
 382 abilities that a current XML language might give us, such as being
 383 able to extract useful portions of the document (all <b>must</b>
 384 directives, for example). There has been quite a bit of discussion
 385 of a new format that would allow for this, probably as part of
 386 switching to DocBook, but as yet such a reorganization and reworking
 387 has not been started.
 388
 389 </li>
 390 </ul>
 391
 392 <p>If you want to work on any of these projects, please mail
 393 <a href="mailto:debian-policy@lists.debian.org">debian-policy@lists.debian.org </a> for more information. We'll be happy to
 394 help you get started.
 395 </p>
 396
 397 </div>
 398
 399 <div id="outline-container-4.1" class="outline-3">
 400 <h3 id="sec-4.1">Maintenance procedures </h3>
 401 <div class="outline-text-3" id="text-4.1">
 402
 403
 404 </div>
 405
 406 </div>
 407
 408 <div id="outline-container-4.2" class="outline-3">
 409 <h3 id="sec-4.2">Repository layout </h3>
 410 <div class="outline-text-3" id="text-4.2">
 411
 412
 413 <p>
 414 The Git repository used for Debian Policy has the following branches:
 415 </p>
 416 <ul>
 417 <li>
 418  master:: the current accepted changes that will be in the next release
 419 </li>
 420 <li>
 421  bug&lt;number&gt;-&lt;user&gt;:: changes addressing bug &lt;number&gt;, shepherded by &lt;user&gt;
 422 </li>
 423 <li>
 424  rra:: old history of Russ's arch repository, now frozen
 425 </li>
 426 <li>
 427  srivasta:: old history of Manoj's arch repository
 428
 429 </li>
 430 </ul>
 431 </div>
 432
 433 </div>
 434
 435 <div id="outline-container-4.3" class="outline-3">
 436 <h3 id="sec-4.3">Managing a bug </h3>
 437 <div class="outline-text-3" id="text-4.3">
 438
 439
 440 <p>
 441 The process used by Policy team members to manage a bug, once there is
 442 proposed wording, is:
 443 </p>
 444 <ul>
 445 <li>
 446 Create a bug&lt;number&gt;-&lt;user&gt; branch for the bug, where &lt;number&gt; is
 447 the bug number in the BTS and &lt;user&gt; is a designator of the Policy
 448 team member who is shepherding the bug.
 449 </li>
 450 <li>
 451 Commit wording changes in that branch until consensus is
 452 achieved. Do not modify debian/changelog or upgrading-checklist.html
 453 during this phase. Use the BTS to track who proposed the wording and
 454 who seconded it.
 455 </li>
 456 <li>
 457 git pull master to make sure you have the latest version.
 458 </li>
 459 <li>
 460 Once the change has been approved by enough people, git merge the
 461 branch into master immediately after making the final commit adding
 462 the changelog entry to minimize conflicts.
 463 </li>
 464 <li>
 465 add the debian/changelog and upgrading-checklist.html changes, and
 466 commit to master.
 467 </li>
 468 <li>
 469 Push master out so other people may merge in their own bug branches
 470 without conflicts.
 471 </li>
 472 <li>
 473 Tag the bug as pending and remove other process tags.
 474 </li>
 475 <li>
 476 Delete the now-merged branch.
 477
 478 </li>
 479 </ul>
 480
 481 <p>The Git commands used for this workflow are:
 482 </p>
 483
 484
 485 <pre class="src src-Sh">git checkout -b bug12345-rra master
 486 # edit files
 487 # git add files
 488 git commit
 489 git push origin bug12345-rra
 490 # iterate until good
 491 # update your local master branch
 492 git checkout master
 493 git pull
 494 # If there are changes in master that make the branch not apply cleanly:
 495 : git checkout -b temp master; git merge bug12345-rra
 496 # If error;
 497 : git reset --hard HEAD;
 498 : git checkout bug12345-rra; git branch -D temp
 499 : git merge master
 500 git checkout master
 501 git merge bug12345-rra
 502 # edit debian/changelog and upgrading-checklist.html
 503 git add debian/changelog upgrading-checklist.html
 504 git commit
 505 git push origin master
 506 git branch -d bug12345-rra
 507 git push origin :bug12345-rra
 508 </pre>
 509
 510
 511
 512
 513 <p>
 514 For the debian/changelog entry, use the following format:
 515 </p>
 516
 517
 518 <pre class="example">* &lt;document&gt;: &lt;brief change description&gt;
 519   Wording: &lt;author of wording&gt;
 520   Seconded: &lt;seconder&gt;
 521   Seconded: &lt;seconder&gt;
 522   Closes: &lt;bug numbers&gt;
 523 </pre>
 524
 525
 526
 527
 528 <p>
 529 For example:
 530 </p>
 531
 532
 533 <pre class="example">* Policy: better document version ranking and empty Debian revisions
 534   Wording: Russ Allbery &lt;rra@debian.org&gt;
 535   Seconded: Raphaël Hertzog &lt;hertzog@debian.org&gt;
 536   Seconded: Manoj Srivastava &lt;srivasta@debian.org&gt;
 537   Seconded: Guillem Jover &lt;guillem@debian.org&gt;
 538   Closes: #186700, #458910
 539 </pre>
 540
 541
 542
 543
 544 </div>
 545
 546 </div>
 547
 548 <div id="outline-container-4.4" class="outline-3">
 549 <h3 id="sec-4.4">Updating branches </h3>
 550 <div class="outline-text-3" id="text-4.4">
 551
 552
 553 <p>
 554 After commits to master have been pushed, either by you or by another
 555 Policy team member, you will generally want to update your working bug
 556 branches. The equivalent of the following commands should do that:
 557 </p>
 558
 559
 560
 561 <pre class="src src-Sh">for i in `git show-ref --heads | awk '{print $2}'`; do
 562     j=$(basename $i)
 563     if [ <span style="font-style: italic;">"$j"</span> != <span style="font-style: italic;">"master"</span> ]; then
 564         git checkout $j &amp;&amp; git merge master
 565     fi
 566 done
 567 git push --all origin
 568 </pre>
 569
 570
 571
 572
 573 <p>
 574 assuming that you haven't packed the refs in your repository.
 575 </p>
 576 </div>
 577
 578 </div>
 579
 580 <div id="outline-container-4.5" class="outline-3">
 581 <h3 id="sec-4.5">Making a release </h3>
 582 <div class="outline-text-3" id="text-4.5">
 583
 584
 585 <p>
 586 For a final Policy release, change UNRELEASED to unstable in
 587 debian/changelog and update the timestamp to match the final release
 588 time (dch -r may be helpful for this), update the release date in
 589 upgrading-checklist.html, update Standards-Version in debian/control,
 590 and commit that change. Then do the final release build and make sure
 591 that it builds and installs.
 592 </p>
 593 <p>
 594 Then, tag the repository and push the final changes to Alioth:
 595 </p>
 596
 597
 598
 599 <pre class="src src-Sh">git tag -s v3.8.0.0
 600 git push origin
 601 git push --tags origin
 602 </pre>
 603
 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 <a href="mailto:srivasta@debian.org">&lt;srivasta@debian.org&gt;</a>
 673 </p>
 674 <p class="date"> Date: 2009-09-15 15:48:45 CDT</p>
 675 <p class="creator">HTML generated by org-mode 6.30trans in emacs 23</p>
 676 </div>
 677 </div>
 678 </body>
 679 </html>