<!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN">
<debiandoc>
  <book>
    <titlepag>
      <title>A mechanism for updating Debian Policy documents</title>
      <author>
	<name>Manoj Srivastava</name>
        <email>srivasta@debian.org</email>
      </author>
      <version>$Revision: 1.7 $</version>
      <copyright>
        <copyrightsummary>Copyright &copy; 2000 by Manoj Srivastava. 
        </copyrightsummary>
        <p>
          You are given permission to redistribute this document
          and/or modify it under the terms of the GNU General Public
          License as published by the Free Software Foundation; either
          version 2, or (at your option) any later version.</p>
        <p>
          On Debian GNU/Linux systems, the complete text of the GNU
          General Public License can be found in
          <tt>/usr/share/common-licenses/GPL</tt>. </p>
      </copyright>
    </titlepag>
    <toc detail="sect">
    <chapt>
      <heading>Introduction, and Administrivia</heading>
      <p>
        This document documents the current practice followed in updating
        Debian Policy documents. This mechanism has been designed for
        dealing with policy changes that are light
	weight and can be decided upon within the policy group, by
	near consensus.  In most day-to-day cases, the Policy group
	should and must be able to conduct Policy discussions and
	amendments without the intervention of the Technical Committee
	or other Constitutional issues.  Only in cases of extreme
	dispute (formal objections) should the intervention of
	Constitutional bodies come into play. In any other situation,
	the Policy group should be able to conduct business
	unfettered. A consequence of this goal is that formal
	objections should not be used lightly, else this mechanism
	shall be ineffective.
      </p>
      <p>
	It should be noted that the team responsible for the task of
	updating policy does not act as author or editor of Policy
	itself, that is the task of the Debian Policy mailing list.
      </p>
      <p>
	<em>In the following, the term developer refers to registered
	  Debian developers.</em>
      </p>
      <sect>
	<heading>Guidelines for policy change proposals</heading>
	<p>
	  Policy does not document all existing practice.  It only
	  incorporates a minimal ruleset that is required for systems
	  integration (usually selecting one branch from several
	  equally viable technical options). It is not a best
	  practices document.
	</p>
	<p>
	  Policy changes under this procedure also should almost never
	  (unless directed by the tech-ctte, and perhaps the DPL)
	  cause a change that would make a significant chunk of
	  packages instantly buggy; for such changes, it is better to
	  implement a gradual transition plan, allowing for partial
	  upgrades (and perhaps using release goals as
	  motivators). Part of the rationale for this is common sense;
	  a global change, in the past, has taken time, and having
	  either a large number of RC bugs, or ignoring a large number
	  of bugs that would otherwise be RC seems silly; and, anyway,
	  there are concerns that the policy group does not really
	  have the power to change policy drastically. This is the
	  basis of the maxim <em>policy shall not be used as a stick to beat
            developers with.</em>
	</p>

	<p>
	  Nor does policy <em>always</em> document only existing
	  practices.  What that oft misquoted statement refers to was
	  a part of a larger thesis that is meant to suggest that
	  policy is not the place for testing out design; if a
	  complicated technical proposal is to be made into policy, it
	  should be independently implemented, have all the kinks
	  worked out, and then have that working model be implemented
	  as policy.  Having to change policy back and forth while a
	  design is being worked out needs be avoided.
	</p>

      </sect>
  
    </chapt>
    <chapt>
      <heading>Archives and Personnel</heading>
      <sect>
	<heading>The policy maintainers team</heading>
	<p>
	  The policy document is maintained by a group of people who have
	  access to the CVS repository for the Policy documents;
	  however, this set of people behave more like maintainers
	  rather than authors/editors. This group does not create
	  policy, nor does it exercise editorial control, Policy is
	  decided "upstream".  The group that decides on policy should
	  be the group of developers on the debian-policy mailing
	  list, which is how it was always done; so the group of
	  policy maintainers have no real power over policy.
	</p>
	<p>
	  Since the policy maintainers have no special powers, there
	  is no restriction of their participation the discussion. It
	  is preferable to have at least 4-5 people on the job,
	  perhaps closer to 8, so that policy does not languish when
	  any maintainer goes missing (we do need vacations, you know,
	  once in a while), and since little creative power is vested
	  in the maintainers, we do not need a central control. And
	  the BTS can be used as a record of the action decided upon
	  even if all maintainers are away at some time.
	</p>
      </sect>
      <sect>
	<heading>The CVS Repository</heading>
	<p>
	  There is a repository set up on <tt>cvs.debian.org</tt> for
	  this, and the people on the policy maintainer team have
	  write access to it. The Debian policy mailing list gets
	  copies of all the CVS commit notices.
	</p>
      </sect>
    </chapt>
    <chapt>
      <heading>Procedures and Processes</heading>

      <sect>
	<heading>Initiating discussions</heading>
	<p>
	  Unlike before, when the policy editor gathered in issues
	  which, in his view, were candidates for inclusion in policy,
	  any one can raise an issue in the mailing list. It is
	  advisable, but by no means mandatory, that the proposer
	  tries an idea out on the mailing list, which can help flesh
	  out details rapidly, and test the sentiment and the
	  collective wisdom of the list. Discussion may be initiated by
	  any member of the list. 
	</p>
	<p>
	  Once the proposer is satisfied that the proposal has merit
	  (with or without trying the waters on the list), the
	  proposer should file a <em>wishlist</em> bug against the
	  debian-policy package. This stage can be initiated by any
	  member of the list.
	</p>
      </sect>
      <sect>
	<heading>Creating a proposal</heading>

	<p>
	  Any Debian developer can create a proposal by retitling the
	  wishlist bug in the BTS to have the subject of the form
	  <strong>"[PROPOSED] ..."</strong> or
	  <strong>"[PROPOSAL] ..."</strong>. (Note: The developer may
	  coalesce these steps into one by directly filing a
	  <em>wishlist</em> bug with the proper subject format).
	</p>
	<p>
	  This is the pre-discussion period, when the idea is kicked
	  around, and polished. There is no preset time limit, but at
	  some point, if it is stalled, the bug should be closed. A
	  suggested time period is 6 months, since if the
          proposal has had no action in that period, it is very likely
          dead. If six months have actually passed, the bug should be
          retitled <strong>"[OLD PROPOSAL] ..."</strong>, and have the
          severity set to fixed. The maintainers shall flush out old
          proposals after a sufficiently long period of time has
	  elapsed (certainly more than a year or so after the initial
	  proposal).
	</p>
	<p>
	  Developers may second the issue by emailing a message
	  containing the text "seconded" to the proposal in the
	  BTS. Only registered Debian developers may second proposals.
	</p>
      </sect>
      <sect>
	<heading>Creating an Amendment</heading>
	<p>
	  When a proposal in the BTS has acquired two seconds (apart
	  from the proposer), it becomes a formal amendment. The bug
	  severity is raised to "normal" and the bug is retitled to
	  <strong>"[AMENDMENT DD/MM/YYYY] ..."</strong>.  
	</p>
	<p>
	  The rationale behind the requirement for seconders is that
	  it would<enumlist>
	    <item>
	      <p>
		Encourage people to test the waters on the policy
		mailing list, and this could help create an proposal
		with a better chance of success</p>
	    </item>
	    <item>
	      <p>
		Prevent frivolous or ill conceived proposals from
		wasting people's time (if the proposal does not even
		convince two developers, surely this is not ready for
		inclusion in Policy?)</p>
	    </item>
	  </enumlist>
	</p>
	<p>
	  The whole discussion process is meant to be lightweight; if
	  you wish the proposals to be amended, talk to the proposer,
	  and get the amendment in. Or else, post an alternative, and
	  let the  group decide which one is better.
	</p>
	<p>
	  If the process gets very contentious, and needs something
	  like votes on amendments and withdrawal of proposal, then
	  this is not the correct forum for this, and the procedures
	  outlined in the constitution should be followed. Note that
	  only non-technical issues can be resolved using the general
	  resolution protocol; technical issues would hopefully be
	  resolved in the group itself, or the technical committee can
	  be called upon to render a decision.
	</p>
	<p>
	  This document is not supposed to supplant the processes
	  outlined in the constitution, nor is it intended to run
	  around them.
	</p>
      </sect>

      <sect>
	<heading>Final disposition of the proposal</heading>
	<sect1>
	  <heading>An accepted amendment</heading>
	  <p>
	    If the amendment is accepted, the bug is marked
	    forwarded and retitled
	    <strong>"[ACCEPTED DD/MM/YYYY] ..."</strong>.
	  </p>
	</sect1>
	<sect1>
	  <heading>An amendment that stalls or is rejected</heading>
	  <p>
	    If the amendment is stalls, or otherwise fails to pass, it
	    is retitled as <strong>"[REJECTED DD/MM/YYYY] ..."</strong>
	    and has its severity set to <tt>fixed</tt>. 
	  </p>
	</sect1>
      </sect>


      <sect>
	<heading>Deadlines for Tabling Discussions</heading>
	<p>
	  It has been observed in the past that discussions on the
	  mailing list tend to devolve into endless arguments. In
	  order to get away from the debating society aspect, at the
	  time of the formal proposal, a deadline can be set (probably
	  by the proposer, since they are likely to have an idea how
	  contentious the discussion is likely to be) for ending
	  discussion on the issue, which should rarely be less than 10
	  days, and typically two weeks or so. I hope that a hard
	  minimum period need not be set, and that the proposers would
	  be reasonable, and not set too short or too long a time for
	  discussion.
	</p>
	<p>
	  If a consensus is reached by the policy group, then the
	  maintainers shall enter the amendment into the Policy
	  document, announce the inclusion in the periodic report, and
	  release a new version.</p>
	<sect1>
	  <heading>Extensions to Deadlines?</heading>
	  <p>
	    If a deadline is approaching, and the discussion is almost
	    concluded (in other words, it has not reached an impasse),
	    and the consensus on the policy group is that an extension
	    of a week would resolve the issues better, a one-time
	    extension could be granted. Care should be taken in
	    exercising this option, since abusing this would merely
	    postpone closures. Anything that is still not resolved is
	    too contentious not to be sent to the full set of
	    developers in a general resolution proposal.
	  </p>
	</sect1>
      </sect>
      <sect>
	<heading>Deadlock resolution</heading>
	<p>
	  Formerly, arriving at a consensus was the only way to amend
	  Policy. That worked well when the Project was small,
	  however, we have apparently grown out of that phase, and even
	  the policy mailing list has grown more fractious than in the
	  days of yore. We now need a formal process of deadlock
	  resolution, and we need to recognize that on non-technical
	  issues a small minority should not always hold up deployment
	  of policy.</p>
	<p>
	  If a consensus is not reached, (or if someone submits a
	  formal objection to the proposal) and the end of the
	  discussion period is near, then one is faced with a dilemma.
	</p>
	<sect1>
	  <heading>Impasse on Technical Issues</heading>
	  <p>
	    On technical issues, popularity is a bad way of arriving
	    at conclusions. Hopefully, the policy group would arrive
	    at a consensus on their own. If that fails to happen, or
	    if there is a formal objection raised on the issue, and
	    the issue is a technical one, then the technical committee
	    may be consulted. This should be a rare occurrence. </p>
	</sect1>
	<sect1>
	  <heading>Non Technical and Subjective Disagreements</heading>
	  <p>
	    However, if the issue is non-technical and subjective,
	    then a vote of the developers may be taken (USENET voting
	    software should be available all over the place, right?),
	    and a super-majority of 75% is needed to carry the
	    amendment through. Failing the super-majority, the issue
	    should be shelved. It may be re-submitted as a a fresh
	    proposal after a suitable cooling off period (which should
	    be no less than a month, typically three months being
	    desirable, unless there are significant new
	    developments). (Demote bug, if the BTS is being used)</p>
	  <p>
	    If the issue raised is especially contentious, or is
	    deemed to be suitable for review by the full set of
	    developers, then four or more developers can call for a
	    hold on the proposal, and move to send the proposal to the
	    larger developer body as a General
	    Resolution. <strong>Note:</strong> The constitution may
	    have additional requirements for submitting a General
	    Resolution, for example, a minimum number of seconders,
	    etc.
	  </p>
	</sect1>
      </sect>
    </chapt>

  </book>
</debiandoc>