This file is indexed.

/usr/share/doc/debian-policy/README.html is in debian-policy 3.9.6.1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Debian Policy</title>
<!-- 2014-11-22 Sat 11:59 -->
<meta  http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta  name="generator" content="Org-mode" />
<meta  name="author" content="Manoj Srivastava And Russ Allbery" />
<style type="text/css">
 <!--/*--><![CDATA[/*><!--*/
  .title  { text-align: center; }
  .todo   { font-family: monospace; color: red; }
  .done   { color: green; }
  .tag    { background-color: #eee; font-family: monospace;
            padding: 2px; font-size: 80%; font-weight: normal; }
  .timestamp { color: #bebebe; }
  .timestamp-kwd { color: #5f9ea0; }
  .right  { margin-left: auto; margin-right: 0px;  text-align: right; }
  .left   { margin-left: 0px;  margin-right: auto; text-align: left; }
  .center { margin-left: auto; margin-right: auto; text-align: center; }
  .underline { text-decoration: underline; }
  #postamble p, #preamble p { font-size: 90%; margin: .2em; }
  p.verse { margin-left: 3%; }
  pre {
    border: 1px solid #ccc;
    box-shadow: 3px 3px 3px #eee;
    padding: 8pt;
    font-family: monospace;
    overflow: auto;
    margin: 1.2em;
  }
  pre.src {
    position: relative;
    overflow: visible;
    padding-top: 1.2em;
  }
  pre.src:before {
    display: none;
    position: absolute;
    background-color: white;
    top: -10px;
    right: 10px;
    padding: 3px;
    border: 1px solid black;
  }
  pre.src:hover:before { display: inline;}
  pre.src-sh:before    { content: 'sh'; }
  pre.src-bash:before  { content: 'sh'; }
  pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
  pre.src-R:before     { content: 'R'; }
  pre.src-perl:before  { content: 'Perl'; }
  pre.src-java:before  { content: 'Java'; }
  pre.src-sql:before   { content: 'SQL'; }

  table { border-collapse:collapse; }
  caption.t-above { caption-side: top; }
  caption.t-bottom { caption-side: bottom; }
  td, th { vertical-align:top;  }
  th.right  { text-align: center;  }
  th.left   { text-align: center;   }
  th.center { text-align: center; }
  td.right  { text-align: right;  }
  td.left   { text-align: left;   }
  td.center { text-align: center; }
  dt { font-weight: bold; }
  .footpara:nth-child(2) { display: inline; }
  .footpara { display: block; }
  .footdef  { margin-bottom: 1em; }
  .figure { padding: 1em; }
  .figure p { text-align: center; }
  .inlinetask {
    padding: 10px;
    border: 2px solid gray;
    margin: 10px;
    background: #ffffcc;
  }
  #org-div-home-and-up
   { text-align: right; font-size: 70%; white-space: nowrap; }
  textarea { overflow-x: auto; }
  .linenr { font-size: smaller }
  .code-highlighted { background-color: #ffff00; }
  .org-info-js_info-navigation { border-style: none; }
  #org-info-js_console-label
    { font-size: 10px; font-weight: bold; white-space: nowrap; }
  .org-info-js_search-highlight
    { background-color: #ffff00; color: #000000; font-weight: bold; }
  /*]]>*/-->
</style>
<script type="text/javascript">
/*
@licstart  The following is the entire license notice for the
JavaScript code in this tag.

Copyright (C) 2012-2013 Free Software Foundation, Inc.

The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version.  The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU GPL for more details.

As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.


@licend  The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
 function CodeHighlightOn(elem, id)
 {
   var target = document.getElementById(id);
   if(null != target) {
     elem.cacheClassElem = elem.className;
     elem.cacheClassTarget = target.className;
     target.className = "code-highlighted";
     elem.className   = "code-highlighted";
   }
 }
 function CodeHighlightOff(elem, id)
 {
   var target = document.getElementById(id);
   if(elem.cacheClassElem)
     elem.className = elem.cacheClassElem;
   if(elem.cacheClassTarget)
     target.className = elem.cacheClassTarget;
 }
/*]]>*///-->
</script>
</head>
<body>
<div id="content">
<h1 class="title">Debian Policy</h1>
<div id="outline-container-sec-1" class="outline-2">
<h2 id="sec-1">Infrastructure</h2>
<div class="outline-text-2" id="text-1">
<ul class="org-ul">
<li>Website:: <a href="http://www.debian.org/doc/devel-manuals#policy">http://www.debian.org/doc/devel-manuals#policy</a>
</li>
<li>Mailing list:: debian-policy@lists.debian.org lists
</li>
<li>Source Code::
<ul class="org-ul">
<li>git clone git://anonscm.debian.org/dbnpolicy/policy.git
</li>
<li>Browser: <a href="http://anonscm.debian.org/gitweb/?p=dbnpolicy/policy.git">http://anonscm.debian.org/gitweb/?p=dbnpolicy/policy.git</a> 
</li>
</ul>
</li>
<li>Unix group:: dbnpolicy
</li>
<li>Alioth Project:: <a href="http://alioth.debian.org/projects/dbnpolicy">http://alioth.debian.org/projects/dbnpolicy</a> (exists
to manage the repository but not otherwise used)
</li>
</ul>
</div>

<div id="outline-container-sec-1-1" class="outline-3">
<h3 id="sec-1-1">Interacting with the team</h3>
<div class="outline-text-3" id="text-1-1">
<ul class="org-ul">
<li>Email contact:: <a href="mailto:debian-policy@lists.debian.org">mailto:debian-policy@lists.debian.org</a>
</li>
<li>Request tracker:: <a href="http://bugs.debian.org/src:debian-policy">http://bugs.debian.org/src:debian-policy</a>
</li>
</ul>

<p>
Debian Policy uses a formal procedure and a set of user tags to manage
the lifecycle of change proposals. For definitions of those tags and
proposal states and information about what the next step is for each
phase, see <a href="./Process.html">Policy changes process</a>.
</p>

<p>
Once the wording for a change has been finalized, please send a patch
against the current Git master branch to the bug report, if you're not
familiar with Git, the following commands are the basic process:
</p>

<div class="org-src-container">

<pre class="src src-Sh">git clone git://anonscm.debian.org/dbnpolicy/policy.git
git checkout -b &lt;local-branch-name&gt;

# edit files, but don't make changes to upgrading-checklist or debian/changelog
git add &lt;files&gt;
git commit
# repeat as necessary

# update your branch against the current master
git checkout master
git pull

git checkout master
git merge --no-commit &lt;local-branch-name&gt;
git reset --hard HEAD;
git checkout &lt;local-branch-name&gt;; 

# If there are changes in master that make the branch not apply cleanly, there
# should have been en error during the merge step above. If there was an
# error, merge the master branch into the local branch, fix the conflicts, and
# commit the new version of the local branch.
 : git merge master
# Edit files to remove conflict
 : git commit -s 

# Checkout the local branch, to create the patch to send to the policy
git checkout &lt;local-branch-name&gt;
dir=$(mktemp -d)
git format-patch -o $dir -s master
# check out the patches created in $dir
git send-email --from "you &lt;your@email&gt;"             \
	       --to debian-policy@lists.debian.org   \
	       $dir/
</pre>
</div>

<p>
&lt;local-branch-name&gt; is some convenient name designating your local
changes. You may want to use some common prefix like local-. You can
use git format-patch and git send-email if you want, but usually it's
overkill.
</p>
</div>
</div>
</div>

<div id="outline-container-sec-2" class="outline-2">
<h2 id="sec-2">Usual Roles</h2>
<div class="outline-text-2" id="text-2">
<p>
The Debian Policy team are official project delegates (see the DPL
delegation). All of the Policy team members do basically the same
work: shepherd proposals, propose wording, and merge changes when
consensus has been reached. The current delegates are:
</p>

<ul class="org-ul">
<li>Andreas Barth (aba)
</li>
<li>Bill Allombert (ballombe)
</li>
<li>Jonathan Nieder (jrnieder)
</li>
<li>Russ Allbery (rra)
</li>
</ul>
</div>
</div>

<div id="outline-container-sec-3" class="outline-2">
<h2 id="sec-3">Task description</h2>
<div class="outline-text-2" id="text-3">
<p>
The Debian Policy team is responsible for maintaining and coordinating
updates to the Debian Policy Manual and all the other policy documents
released as part of the "debian-policy" package.
</p>

<p>
The Debian Policy Editors:
</p>

<ul class="org-ul">
<li>Guide the work on the Debian Policy Manual and related documents as a
collaborative process where developers review and second or object to
proposals, usually on the debian-policy mailing list.
</li>

<li>Count seconds and weight objections to proposals, to determine whether
they have reached sufficient consensus to be included, and accept
consensual proposals.
</li>

<li>Reject or refer to the Technical Committee proposals that fail to
reach consensus.
</li>

<li>Commit changes to the version control system repository used to
maintain the Debian Policy Manual and related documents.
</li>

<li>Maintain the "debian-policy" package. As package maintainers, they
have the last word on package content, releases, bug reports, etc.
</li>
</ul>

<p>
Everything else can be done by anyone, or any DD (depending on the
outcome of the discussion about seconding). We explicitly want any
Debian DD to review and second or object to proposals. The more
participation, the better. Many other people are active on the Policy
mailing list without being project delegates.
</p>

<p>
In addition to the main technical manual, the team currently also maintains:
</p>

<ul class="org-ul">
<li><a href="http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/">Machine-readable debian/copyright format</a>
</li>
<li><a href="http://www.debian.org/doc/packaging-manuals/menu-policy/">Debian Menu sub-policy</a>
</li>
<li><a href="http://www.debian.org/doc/packaging-manuals/perl-policy/">Debian Perl Policy</a>
</li>
<li><a href="http://www.debian.org/doc/packaging-manuals/debconf_specification.html">Debconf Specification</a>
</li>
<li><a href="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt">Authoritative list of virtual package names </a>
</li>
</ul>

<p>
These documents are maintained using the <a href="./Process.html">Policy changes process</a>, and
the current state of all change proposals is tracked using the
<a href="http://bugs.debian.org/src:debian-policy">debian-policy BTS</a>.
</p>
</div>
</div>

<div id="outline-container-sec-4" class="outline-2">
<h2 id="sec-4">Get involved</h2>
<div class="outline-text-2" id="text-4">
<p>
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
that no one is currently shepherding (ask on
<a href="mailto:debian-policy@lists.debian.org">debian-policy@lists.debian.org</a> if you're not sure if a particular bug
is being shepherded), and help it through the change process. This
will involve guiding the discussion, seeking additional input
(particularly from experts in the area being discussed), possibly
raising the issue on other mailing lists, proposing or getting other
people to propose specific wording changes, and writing diffs against
the current Policy document. All of the steps of <a href="./Process.html">Policy changes process</a> 
can be done by people other than Policy team members except
the final acceptance steps and almost every change can be worked on
independently, so there's a lot of opportunity for people to help.
</p>

<p>
There are also some other, larger projects:
</p>

<ul class="org-ul">
<li>Policy is currently maintained in DebianDoc-SGML, which is no longer
very actively maintained and isn't a widely used or understood
format. The most logical replacement would be DocBook. However,
DocBook is a huge language with many tags and options, making it
rather overwhelming. We badly need someone with DocBook experience
to write a style guide specifying exactly which tags should be used
and what they should be used for so that we can limit ourselves to
an easy-to-understand and documented subset of the language.
</li>
<li>Policy contains several appendices which are really documentation of
how parts of the dpkg system works rather than technical
Policy. Those appendices should be removed from the Policy document
and maintained elsewhere, probably as part of dpkg, and any Policy
statements in them moved into the main document. This project will
require reviewing the current contents of the appendices and feeding
the useful bits that aren't currently documented back to the dpkg
team as documentation patches.
</li>
<li>Policy has grown organically over the years and suffers from
organizational issues because of it. It also doesn't make use of the
abilities that a current XML language might give us, such as being
able to extract useful portions of the document (all <b>must</b>
directives, for example). There has been quite a bit of discussion
of a new format that would allow for this, probably as part of
switching to DocBook, but as yet such a reorganization and reworking
has not been started.
</li>
</ul>

<p>
If you want to work on any of these projects, please mail
<a href="mailto:debian-policy@lists.debian.org">debian-policy@lists.debian.org </a> for more information. We'll be happy to
help you get started.
</p>
</div>

<div id="outline-container-sec-4-1" class="outline-3">
<h3 id="sec-4-1">Maintenance procedures</h3>
</div>

<div id="outline-container-sec-4-2" class="outline-3">
<h3 id="sec-4-2">Repository layout</h3>
<div class="outline-text-3" id="text-4-2">
<p>
The Git repository used for Debian Policy has the following branches:
</p>

<ul class="org-ul">
<li>master:: the current accepted changes that will be in the next release
</li>
<li>bug&lt;number&gt;-&lt;user&gt;:: changes addressing bug &lt;number&gt;, shepherded by &lt;user&gt;
</li>
<li>rra:: old history of Russ's arch repository, now frozen
</li>
<li>srivasta:: old history of Manoj's arch repository 
</li>
</ul>
</div>
</div>

<div id="outline-container-sec-4-3" class="outline-3">
<h3 id="sec-4-3">Managing a bug</h3>
<div class="outline-text-3" id="text-4-3">
<p>
The process used by Policy team members to manage a bug, once there is
proposed wording, is:
</p>

<ul class="org-ul">
<li>Create a bug&lt;number&gt;-&lt;user&gt; branch for the bug, where &lt;number&gt; is
the bug number in the BTS and &lt;user&gt; is a designator of the Policy
team member who is shepherding the bug.
</li>
<li>Commit wording changes in that branch until consensus is
achieved. Do not modify debian/changelog or upgrading-checklist.html
during this phase. Use the BTS to track who proposed the wording and
who seconded it.
</li>
<li>git pull master to make sure you have the latest version.
</li>
<li>Once the change has been approved by enough people, git merge the
branch into master immediately after making the final commit adding
the changelog entry to minimize conflicts.
</li>
<li>add the debian/changelog and upgrading-checklist.html changes, and
commit to master.
</li>
<li>Push master out so other people may merge in their own bug branches
without conflicts.
</li>
<li>Tag the bug as pending and remove other process tags.
</li>
<li>Delete the now-merged branch.
</li>
</ul>

<p>
The Git commands used for this workflow are:
</p>
<div class="org-src-container">

<pre class="src src-Sh">git checkout -b bug12345-rra master
# edit files
# git add files
git commit
git push origin bug12345-rra
# iterate until good
# update your local master branch
git checkout master
git pull

git checkout master
git merge --no-commit bug12345-rra
git reset --hard HEAD;

# If there are changes in master that make the branch not apply cleanly, there
# should have been en error during the merge step above. If there was an
# error, merge the master branch into the local branch, fix the conflicts, and
# commit the new version of the local branch.
 : git checkout bug12345-rra
 : git merge master
# Edit files to remove conflict
 : git commit -s 

git checkout master
git merge bug12345-rra
# edit debian/changelog and upgrading-checklist.html
git add debian/changelog upgrading-checklist.html
git commit
git push origin master
git branch -d bug12345-rra
git push origin :bug12345-rra
</pre>
</div>

<p>
For the debian/changelog entry, use the following format:
</p>
<pre class="example">
* &lt;document&gt;: &lt;brief change description&gt;
  Wording: &lt;author of wording&gt;
  Seconded: &lt;seconder&gt;
  Seconded: &lt;seconder&gt;
  Closes: &lt;bug numbers&gt;
</pre>

<p>
For example:
</p>
<pre class="example">
* Policy: better document version ranking and empty Debian revisions
  Wording: Russ Allbery &lt;rra@debian.org&gt;
  Seconded: Raphaƫl Hertzog &lt;hertzog@debian.org&gt;
  Seconded: Manoj Srivastava &lt;srivasta@debian.org&gt;
  Seconded: Guillem Jover &lt;guillem@debian.org&gt;
  Closes: #186700, #458910
</pre>
</div>
</div>

<div id="outline-container-sec-4-4" class="outline-3">
<h3 id="sec-4-4">Updating branches</h3>
<div class="outline-text-3" id="text-4-4">
<p>
After commits to master have been pushed, either by you or by another
Policy team member, you will generally want to update your working bug
branches. The equivalent of the following commands should do that:
</p>

<div class="org-src-container">

<pre class="src src-Sh">for i in `git show-ref --heads | awk '{print $2}'`; do
    j=$(basename $i)
    if [ "$j" != "master" ]; then
	git checkout $j &amp;&amp; git merge master
    fi
done
git push --all origin
</pre>
</div>

<p>
assuming that you haven't packed the refs in your repository.
</p>
</div>
</div>

<div id="outline-container-sec-4-5" class="outline-3">
<h3 id="sec-4-5">Making a release</h3>
<div class="outline-text-3" id="text-4-5">
<p>
For a final Policy release, change UNRELEASED to unstable in
debian/changelog and update the timestamp to match the final release
time (dch -r may be helpful for this), update the release date in
upgrading-checklist.html, update Standards-Version in debian/control,
and commit that change. Then do the final release build and make sure
that it builds and installs.
</p>

<p>
Then, tag the repository and push the final changes to Alioth:
</p>

<div class="org-src-container">

<pre class="src src-Sh">git tag -s v3.8.0.0
git push origin
git push --tags origin
</pre>
</div>

<p>
replacing the version number with the version of the release, of course.
</p>

<p>
Finally, announce the new Policy release on debian-devel-announce,
including in the announcement the upgrading-checklist section for the
new release.
</p>
</div>
</div>

<div id="outline-container-sec-4-6" class="outline-3">
<h3 id="sec-4-6">Setting release goals</h3>
<div class="outline-text-3" id="text-4-6">
<p>
Policy has a large bug backlog, and each bug against Policy tends to
take considerable time and discussion to resolve. I've found it
useful, when trying to find a place to start, to pick a manageable set
of bugs and set as a target resolving them completely before the next
Policy release. Resolving a bug means one of the following:
</p>

<ul class="org-ul">
<li>Proposing new language to address the bug that's seconded and approved by
the readers of the Policy list following the <a href="./Progress.html">Policy changes process</a> (or
that's accepted by one of the Policy delegates if the change isn't
normative; i.e., doesn't change the technical meaning of the document).
</li>
<li>Determining that the bug is not relevant to Policy and closing it.
</li>
<li>Determining that either there is no consensus that the bug indicates
a problem, that the solutions that we can currently come up with are
good solutions, or that Debian is ready for the change. These bugs
are tagged wontfix and then closed after a while. A lot of Policy
bugs fall into this category; just because it would be useful to
have a policy in some area doesn't mean that we're ready to make
one, and keeping the bugs open against Policy makes it difficult to
tell what requires work. If the problem is worth writing a policy
for, it will come up again later when hopefully the project
consensus is more mature.
</li>
</ul>

<p>
Anyone can pick bugs and work resolve them. The final determination to
accept a wording change or reject a bug will be made by a Policy
delegate, but if a patch is already written and seconded, or if a
summary of why a bug is not ready to be acted on is already written,
the work is much easier for the Policy delegate.
</p>

<p>
One of the best ways to help out is to pick one or two bugs (checking
on the Policy list first), say that you'll make resolving them a goal
for the next release, and guide the discussion until the bugs can
reach one of the resolution states above.
</p>
</div>
</div>
</div>
</div>
<div id="postamble" class="status">
<p class="author">Author: Manoj Srivastava And Russ Allbery</p>
<p class="date">Created: 2014-11-22 Sat 11:59</p>
<p class="creator"><a href="http://www.gnu.org/software/emacs/">Emacs</a> 24.4.1 (<a href="http://orgmode.org">Org</a> mode 8.2.10)</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>
</html>