policy-process.sgml

   1 <!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN">
   2 <debiandoc>
   3   <book>
   4     <titlepag>
   5       <title>A mechanism for updating Debian Policy documents</title>
   6       <author>
   7         <name>Manoj Srivastava</name>
   8         <email>srivasta@debian.org</email>
   9       </author>
  10       <version>$Revision: 1.7 $</version>
  11       <copyright>
  12         <copyrightsummary>Copyright &copy; 2000 by Manoj Srivastava.
  13         </copyrightsummary>
  14         <p>
  15           You are given permission to redistribute this document
  16           and/or modify it under the terms of the GNU General Public
  17           License as published by the Free Software Foundation; either
  18           version 2, or (at your option) any later version.</p>
  19         <p>
  20           On Debian GNU/Linux systems, the complete text of the GNU
  21           General Public License can be found in
  22           <tt>/usr/share/common-licenses/GPL</tt>. </p>
  23       </copyright>
  24     </titlepag>
  25     <toc detail="sect">
  26     <chapt>
  27       <heading>Introduction, and Administrivia</heading>
  28       <p>
  29         This document documents the current practice followed in updating
  30         Debian Policy documents. This mechanism has been designed for
  31         dealing with policy changes that are light
  32         weight and can be decided upon within the policy group, by
  33         near consensus.  In most day-to-day cases, the Policy group
  34         should and must be able to conduct Policy discussions and
  35         amendments without the intervention of the Technical Committee
  36         or other Constitutional issues.  Only in cases of extreme
  37         dispute (formal objections) should the intervention of
  38         Constitutional bodies come into play. In any other situation,
  39         the Policy group should be able to conduct business
  40         unfettered. A consequence of this goal is that formal
  41         objections should not be used lightly, else this mechanism
  42         shall be ineffective.
  43       </p>
  44       <p>
  45         It should be noted that the team responsible for the task of
  46         updating policy does not act as author or editor of Policy
  47         itself, that is the task of the Debian Policy mailing list.
  48       </p>
  49       <p>
  50         <em>In the following, the term developer refers to registered
  51           Debian developers.</em>
  52       </p>
  53       <sect>
  54         <heading>Guidelines for policy change proposals</heading>
  55         <p>
  56           Policy does not document all existing practice.  It only
  57           incorporates a minimal ruleset that is required for systems
  58           integration (usually selecting one branch from several
  59           equally viable technical options). It is not a best
  60           practices document.
  61         </p>
  62         <p>
  63           Policy changes under this procedure also should almost never
  64           (unless directed by the tech-ctte, and perhaps the DPL)
  65           cause a change that would make a significant chunk of
  66           packages instantly buggy; for such changes, it is better to
  67           implement a gradual transition plan, allowing for partial
  68           upgrades (and perhaps using release goals as
  69           motivators). Part of the rationale for this is common sense;
  70           a global change, in the past, has taken time, and having
  71           either a large number of RC bugs, or ignoring a large number
  72           of bugs that would otherwise be RC seems silly; and, anyway,
  73           there are concerns that the policy group does not really
  74           have the power to change policy drastically. This is the
  75           basis of the maxim <em>policy shall not be used as a stick to beat
  76             developers with.</em>
  77         </p>
  78
  79         <p>
  80           Nor does policy <em>always</em> document only existing
  81           practices.  What that oft misquoted statement refers to was
  82           a part of a larger thesis that is meant to suggest that
  83           policy is not the place for testing out design; if a
  84           complicated technical proposal is to be made into policy, it
  85           should be independently implemented, have all the kinks
  86           worked out, and then have that working model be implemented
  87           as policy.  Having to change policy back and forth while a
  88           design is being worked out needs be avoided.
  89         </p>
  90
  91       </sect>
  92
  93     </chapt>
  94     <chapt>
  95       <heading>Archives and Personnel</heading>
  96       <sect>
  97         <heading>The policy maintainers team</heading>
  98         <p>
  99           The policy document is maintained by a group of people who have
 100           access to the CVS repository for the Policy documents;
 101           however, this set of people behave more like maintainers
 102           rather than authors/editors. This group does not create
 103           policy, nor does it exercise editorial control, Policy is
 104           decided "upstream".  The group that decides on policy should
 105           be the group of developers on the debian-policy mailing
 106           list, which is how it was always done; so the group of
 107           policy maintainers have no real power over policy.
 108         </p>
 109         <p>
 110           Since the policy maintainers have no special powers, there
 111           is no restriction of their participation the discussion. It
 112           is preferable to have at least 4-5 people on the job,
 113           perhaps closer to 8, so that policy does not languish when
 114           any maintainer goes missing (we do need vacations, you know,
 115           once in a while), and since little creative power is vested
 116           in the maintainers, we do not need a central control. And
 117           the BTS can be used as a record of the action decided upon
 118           even if all maintainers are away at some time.
 119         </p>
 120       </sect>
 121       <sect>
 122         <heading>The CVS Repository</heading>
 123         <p>
 124           There is a repository set up on <tt>cvs.debian.org</tt> for
 125           this, and the people on the policy maintainer team have
 126           write access to it. The Debian policy mailing list gets
 127           copies of all the CVS commit notices.
 128         </p>
 129       </sect>
 130     </chapt>
 131     <chapt>
 132       <heading>Procedures and Processes</heading>
 133
 134       <sect>
 135         <heading>Initiating discussions</heading>
 136         <p>
 137           Unlike before, when the policy editor gathered in issues
 138           which, in his view, were candidates for inclusion in policy,
 139           any one can raise an issue in the mailing list. It is
 140           advisable, but by no means mandatory, that the proposer
 141           tries an idea out on the mailing list, which can help flesh
 142           out details rapidly, and test the sentiment and the
 143           collective wisdom of the list. Discussion may be initiated by
 144           any member of the list.
 145         </p>
 146         <p>
 147           Once the proposer is satisfied that the proposal has merit
 148           (with or without trying the waters on the list), the
 149           proposer should file a <em>wishlist</em> bug against the
 150           debian-policy package. This stage can be initiated by any
 151           member of the list.
 152         </p>
 153       </sect>
 154       <sect>
 155         <heading>Creating a proposal</heading>
 156
 157         <p>
 158           Any Debian developer can create a proposal by retitling the
 159           wishlist bug in the BTS to have the subject of the form
 160           <strong>"[PROPOSED] ..."</strong> or
 161           <strong>"[PROPOSAL] ..."</strong>. (Note: The developer may
 162           coalesce these steps into one by directly filing a
 163           <em>wishlist</em> bug with the proper subject format).
 164         </p>
 165         <p>
 166           This is the pre-discussion period, when the idea is kicked
 167           around, and polished. There is no preset time limit, but at
 168           some point, if it is stalled, the bug should be closed. A
 169           suggested time period is 6 months, since if the
 170           proposal has had no action in that period, it is very likely
 171           dead. If six months have actually passed, the bug should be
 172           retitled <strong>"[OLD PROPOSAL] ..."</strong>, and have the
 173           severity set to fixed. The maintainers shall flush out old
 174           proposals after a sufficiently long period of time has
 175           elapsed (certainly more than a year or so after the initial
 176           proposal).
 177         </p>
 178         <p>
 179           Developers may second the issue by emailing a message
 180           containing the text "seconded" to the proposal in the
 181           BTS. Only registered Debian developers may second proposals.
 182         </p>
 183       </sect>
 184       <sect>
 185         <heading>Creating an Amendment</heading>
 186         <p>
 187           When a proposal in the BTS has acquired two seconds (apart
 188           from the proposer), it becomes a formal amendment. The bug
 189           severity is raised to "normal" and the bug is retitled to
 190           <strong>"[AMENDMENT DD/MM/YYYY] ..."</strong>.
 191         </p>
 192         <p>
 193           The rationale behind the requirement for seconders is that
 194           it would<enumlist>
 195             <item>
 196               <p>
 197                 Encourage people to test the waters on the policy
 198                 mailing list, and this could help create an proposal
 199                 with a better chance of success</p>
 200             </item>
 201             <item>
 202               <p>
 203                 Prevent frivolous or ill conceived proposals from
 204                 wasting people's time (if the proposal does not even
 205                 convince two developers, surely this is not ready for
 206                 inclusion in Policy?)</p>
 207             </item>
 208           </enumlist>
 209         </p>
 210         <p>
 211           The whole discussion process is meant to be lightweight; if
 212           you wish the proposals to be amended, talk to the proposer,
 213           and get the amendment in. Or else, post an alternative, and
 214           let the  group decide which one is better.
 215         </p>
 216         <p>
 217           If the process gets very contentious, and needs something
 218           like votes on amendments and withdrawal of proposal, then
 219           this is not the correct forum for this, and the procedures
 220           outlined in the constitution should be followed. Note that
 221           only non-technical issues can be resolved using the general
 222           resolution protocol; technical issues would hopefully be
 223           resolved in the group itself, or the technical committee can
 224           be called upon to render a decision.
 225         </p>
 226         <p>
 227           This document is not supposed to supplant the processes
 228           outlined in the constitution, nor is it intended to run
 229           around them.
 230         </p>
 231       </sect>
 232
 233       <sect>
 234         <heading>Final disposition of the proposal</heading>
 235         <sect1>
 236           <heading>An accepted amendment</heading>
 237           <p>
 238             If the amendment is accepted, the bug is marked
 239             forwarded and retitled
 240             <strong>"[ACCEPTED DD/MM/YYYY] ..."</strong>.
 241           </p>
 242         </sect1>
 243         <sect1>
 244           <heading>An amendment that stalls or is rejected</heading>
 245           <p>
 246             If the amendment is stalls, or otherwise fails to pass, it
 247             is retitled as <strong>"[REJECTED DD/MM/YYYY] ..."</strong>
 248             and has its severity set to <tt>fixed</tt>.
 249           </p>
 250         </sect1>
 251       </sect>
 252
 253
 254       <sect>
 255         <heading>Deadlines for Tabling Discussions</heading>
 256         <p>
 257           It has been observed in the past that discussions on the
 258           mailing list tend to devolve into endless arguments. In
 259           order to get away from the debating society aspect, at the
 260           time of the formal proposal, a deadline can be set (probably
 261           by the proposer, since they are likely to have an idea how
 262           contentious the discussion is likely to be) for ending
 263           discussion on the issue, which should rarely be less than 10
 264           days, and typically two weeks or so. I hope that a hard
 265           minimum period need not be set, and that the proposers would
 266           be reasonable, and not set too short or too long a time for
 267           discussion.
 268         </p>
 269         <p>
 270           If a consensus is reached by the policy group, then the
 271           maintainers shall enter the amendment into the Policy
 272           document, announce the inclusion in the periodic report, and
 273           release a new version.</p>
 274         <sect1>
 275           <heading>Extensions to Deadlines?</heading>
 276           <p>
 277             If a deadline is approaching, and the discussion is almost
 278             concluded (in other words, it has not reached an impasse),
 279             and the consensus on the policy group is that an extension
 280             of a week would resolve the issues better, a one-time
 281             extension could be granted. Care should be taken in
 282             exercising this option, since abusing this would merely
 283             postpone closures. Anything that is still not resolved is
 284             too contentious not to be sent to the full set of
 285             developers in a general resolution proposal.
 286           </p>
 287         </sect1>
 288       </sect>
 289       <sect>
 290         <heading>Deadlock resolution</heading>
 291         <p>
 292           Formerly, arriving at a consensus was the only way to amend
 293           Policy. That worked well when the Project was small,
 294           however, we have apparently grown out of that phase, and even
 295           the policy mailing list has grown more fractious than in the
 296           days of yore. We now need a formal process of deadlock
 297           resolution, and we need to recognize that on non-technical
 298           issues a small minority should not always hold up deployment
 299           of policy.</p>
 300         <p>
 301           If a consensus is not reached, (or if someone submits a
 302           formal objection to the proposal) and the end of the
 303           discussion period is near, then one is faced with a dilemma.
 304         </p>
 305         <sect1>
 306           <heading>Impasse on Technical Issues</heading>
 307           <p>
 308             On technical issues, popularity is a bad way of arriving
 309             at conclusions. Hopefully, the policy group would arrive
 310             at a consensus on their own. If that fails to happen, or
 311             if there is a formal objection raised on the issue, and
 312             the issue is a technical one, then the technical committee
 313             may be consulted. This should be a rare occurrence. </p>
 314         </sect1>
 315         <sect1>
 316           <heading>Non Technical and Subjective Disagreements</heading>
 317           <p>
 318             However, if the issue is non-technical and subjective,
 319             then a vote of the developers may be taken (USENET voting
 320             software should be available all over the place, right?),
 321             and a super-majority of 75% is needed to carry the
 322             amendment through. Failing the super-majority, the issue
 323             should be shelved. It may be re-submitted as a a fresh
 324             proposal after a suitable cooling off period (which should
 325             be no less than a month, typically three months being
 326             desirable, unless there are significant new
 327             developments). (Demote bug, if the BTS is being used)</p>
 328           <p>
 329             If the issue raised is especially contentious, or is
 330             deemed to be suitable for review by the full set of
 331             developers, then four or more developers can call for a
 332             hold on the proposal, and move to send the proposal to the
 333             larger developer body as a General
 334             Resolution. <strong>Note:</strong> The constitution may
 335             have additional requirements for submitting a General
 336             Resolution, for example, a minimum number of seconders,
 337             etc.
 338           </p>
 339         </sect1>
 340       </sect>
 341     </chapt>
 342
 343   </book>
 344 </debiandoc>