1 <!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN">
5 <title>A mechanism for updating Debian Policy documents</title>
7 <name>Manoj Srivastava</name>
8 <email>srivasta@debian.org</email>
10 <version>$Revision: 1.7 $</version>
12 <copyrightsummary>Copyright © 2000 by Manoj Srivastava.
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>
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>
27 <heading>Introduction, and Administrivia</heading>
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
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.
50 <em>In the following, the term developer refers to registered
51 Debian developers.</em>
54 <heading>Guidelines for policy change proposals</heading>
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
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
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.
95 <heading>Archives and Personnel</heading>
97 <heading>The policy maintainers team</heading>
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.
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.
122 <heading>The CVS Repository</heading>
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.
132 <heading>Procedures and Processes</heading>
135 <heading>Initiating discussions</heading>
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.
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
155 <heading>Creating a proposal</heading>
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).
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
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.
185 <heading>Creating an Amendment</heading>
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>.
193 The rationale behind the requirement for seconders is that
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>
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>
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.
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.
227 This document is not supposed to supplant the processes
228 outlined in the constitution, nor is it intended to run
234 <heading>Final disposition of the proposal</heading>
236 <heading>An accepted amendment</heading>
238 If the amendment is accepted, the bug is marked
239 forwarded and retitled
240 <strong>"[ACCEPTED DD/MM/YYYY] ..."</strong>.
244 <heading>An amendment that stalls or is rejected</heading>
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>.
255 <heading>Deadlines for Tabling Discussions</heading>
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
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>
275 <heading>Extensions to Deadlines?</heading>
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.
290 <heading>Deadlock resolution</heading>
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
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.
306 <heading>Impasse on Technical Issues</heading>
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>
316 <heading>Non Technical and Subjective Disagreements</heading>
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>
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,