web/deps/dep0.mdwn

[[meta title="DEP-0: Introducing Debian Enhancement Proposals (DEPs)"]]

    Title: Introducing Debian Enhancement Proposals (DEPs)
    DEP: 0
    State: DRAFT
    Date: 2008-01-15
    Drivers: Stefano Zacchiroli <zack@debian.org>,
     Adeodato Simó <dato@net.com.org.es>,
     Lars Wirzenius <liw@iki.fi>
    URL: http://dep.debian.net/deps/dep0
    Abstract:
     Workflow for managing discussions about improvements to Debian and
     archiving their outcomes.


Introduction
------------

This is a proposal to organize discussions about Debian enhancements,
reflect their current status and, in particular, to archive their
outcomes, via a new lightweight process based on Debian Enhancement
Proposals (DEPs). This idea is loosely based on existing similar systems
such as RFCs and Python PEPs. It is also completely opt-in, and does not
involve any new committees, powers, or authorities.


Motivation
----------

Currently, when having discussions about improvements to Debian, it is
not always clear when consensus has been reached, and people willing to
implement it may start too early, leading to wasted efforts, or delay it
indefinitely, because there's not clear indication it is time to begin. At the
same time, potential adopters of an enhancement may not be able to
easily assess whether they should use said implementation or not,
because it's difficult to know whether it adjusts to the consensus
reached during the discussion period.

As our normative documents rely on wide adoption of a practice before
documenting it, and adopters can be reluctant to make use of it before a
clear indication that a practice has some consensus behind it, this
creates a hard to break loop that this process hopes to alleviate, by
providing a mechanism to reflect the status of each proposal, including
whether it has reached consensus or not.

Secondly, we lack at the moment a central index in which to list such
proposals, which would be useful to see at a glance what open fronts
there are at a given moment in Debian, and who is taking care of them
and, additionally, to serve as a storage place for successfully
completed proposals, documenting the outcome of the discussion and the
details of the implementation.

By using this process, people involved in developing any enhancement can
help to build such index, with very little overhead required on their
part.


Workflow
--------

A "Debian enhancement" can be pretty much any change to Debian,
technical or otherwise. Examples of situations when the DEP process
might be or might have been used include:

* Introducing new debian/control fields (Homepage, Vcs-*).
* Making debian/copyright be machine parseable.
* Agreeing upon a meta-package name or virtual package name.
* Deciding on a procedure for the Debconf team for assigning travel
  sponsorship money.
* Formalizing existing informal processes or procedures, e.g.,
  the procedure for getting a new architecture added to the archive, or
  getting access to piatti.debian.org to run QA tests.

The workflow is very simple, and is intended to be quite lightweight:
an enhancement to Debian is suggested, discussed, implemented, and
becomes accepted practice (or policy, if applicable), in the normal
Debian way. As the discussion progresses, the enhancement is assigned
certain states, as explained below. During all the process, a single URL
maintained by the proposers can be used to check the status of the
proposal.

The result of all this is:

  1. an implementation of the enhancement and
  2. a document that can be referred to later on without having to dig
     up and read through large discussions.

The actual discussions should happen in the usual forum or forums for
the topic of the DEP. This way, DEPs do not act as yet another forum to
be followed. For example, a DEP suggesting changes to www.debian.org
graphical design should happen on debian-www, as usual.

In the same way, DEPs do not give any extra powers or authority to
anyone: they rely on reaching consensus in the traditional Debian way,
by engaging in discussions on mailing lists, IRC, or real life meetings
as appropriate, and not by consulting an external body for a decision.
To be acceptable, this consensus includes agreement from affected
parties, including those who would have to implement it or accept an
implementation.

The person or people who do the suggestion are the "drivers" of the
proposal and have the responsibility of writing the initial draft, and
of updating it during the discussions, see below.


Proposal states
---------------

The proposal goes through several states over its lifetime. The ideal
progression is DRAFT -> CANDIDATE -> ACCEPTED, but reality requires a
couple of other states as well.

#### DRAFT: discussion until (rough) consensus

  * every new proposal starts as a DRAFT
  * anyone can propose a draft
  * each draft has a number (next free one from document index)
  * normal changes happen in this period
  * drafts should include extra criteria for success (in addition to
    having obtained rough consensus, see below), that is, for moving to
    the ACCEPTED state

#### CANDIDATE: implementation + testing

  * consensus exists for what should be done, and how it should be done
  * agreement needs to be expressed by all affected parties, not just the
    drivers; silence is not agreement, but unanimity is not required, either
  * implementation can of course start earlier
  * changes in this period are primarily based on feedback from implementation
  * this period must be long enough that there is a consensus that the
    enhancement works (on the basis of implementation evaluation)

#### ACCEPTED: integrate to policy/devref/elsewhere (if applicable)

  * consensus exists that the implementation has been a success
  * also, the final version of the document is archived in a central place
    (vcs on alioth, plus web page generated from that), even if integrated
    to other documents as well

#### DROPPED: no further action needed

  * the drivers are no longer interested in pursuing the DEP
  * if there are no modifications to a DEP in DRAFT state for six months,
    or there is a consensus that the implementation of a DEP in
    CANDIDATE state has been abandoned, the DEP is moved to DROPPED
    state (from which it can be resurrected by moving to DRAFT stage
    again)

#### OBSOLETE: no longer relevant

  * for example, when a new revision (as a new DEP) gets accepted, the
    old one will move to OBSOLETE state, and will be modified to refer
    to the new one


What the drivers should do
--------------------------

The additional, hopefully small, burden of the DEP process falls on the
shoulders of its drivers. They have to take care of all the practical
work of writing and maintaining the draft, so that everyone else can
just continue discussing things over e-mail as before.  Driver's burden
can be summarized as:

* Write the draft.
* Update the draft during discussion.
* Determine when (rough) consensus in discussion has been reached.
* Implement, or find volunteers to implement.
* Determine when consensus of implementation success has been reached,
  when the testing of the available implementation has been satisfactory.
* Update the DEP with progress updates at suitable intervals, until the
  DEP has been accepted.

If the drivers go missing in action, other people may step in and
courteously take over the driving position.


Format and content
------------------

A DEP is basically a free-form plain text file, except that it must
start with a paragraph of the following RFC822-style headers:

* Title: the full title of the document
* DEP: the number for this DEP
* State: the current state of this revision
* Date: the date of this revision
* Drivers: a list of drivers (names and e-mail addresses), in RFC822
  syntax for the To: header
* URL: during DRAFT state, a link to the canonical place of the draft
  (typically probably http://wiki.debian.org/DEP/DEPxxx or
  http://dep.debian.net/deps/depXXX)
* Abstract: a short paragraph (formatted as the long Description in
  debian/control)

The rest of the file is free form. If the DEP is kept in a wiki, using
its markup syntax is, of course, a good idea.

Suggested document contents:

* An introduction, giving an overview of the situation and the motivation
  for the DEP.
* A plan for implementation, especially indicating what parts of Debian need
  to be changed, and preferably indicating who will do the work.
* Preferably a list of criteria to judge whether the implementation has been
  a success.
* Links to mailing list threads, perhaps highlighting particularly important
  messages. If discussion happens on IRC, pointers to logs would be nice.


Creating a DEP
--------------

The procedure to create a DEP is simple: send an e-mail to
`debian-project@lists.debian.org`, stating that you're taking the next
available number, and including the first paragraph of the DEP as
explained above. It is very important to include the list of drivers,
and the URL where the draft will be kept up to date. The next available
DEP number can be obtained by consulting <http://dep.debian.net>.

It is also a very good idea to mention in this mail the place where the
discussion is going to take place, with a pointer to the thread in the
mailing list archives if it has already started.

Additionally, drivers are welcome to maintain their DEPs, even in the
draft state, in a repository inside the `dep` Alioth project, following
the instructions at <http://dep.debian.net/howto>. They are free not to
do so, and in that case a DEP0 driver or some interested party will
update the `dep.debian.net` index with their DEP, and a pointer to the
URL they provided.


Revising an accepted DEP
------------------------

If the feature, or whatever, of the DEP needs further changing later,
the process can start over with the accepted version of the DEP document
as the initial draft. The new draft will get a new DEP number. Once the
new DEP is accepted, the old one should move to OBSOLETE state.


TODO
----

* Figure out how to mark up a DEP file in wiki.debian.org's syntax
  in such a way as to make the initial RFC822-style paragraph format
  sensibly, but without making it require much or any wiki markup.
* Mention somewhere explicitly that the location of the index is
  <http://dep.debian.net>.


Changes
-------

* 2008-01-15:
  [ Adeodato Simó ]
  * Add section about how to create a DEP.
  * Rewrite "Introduction" (splitting "Motivation" off), and parts of
    "Workflow" as well.

  [ Lars Wirzenius ]
  * Typo fixes.

* 2008-01-11: Minor tweaks by Zack (mostly cosmetic, but also
  some more detailed specification of former more vague aspects)

* 2008-01-09: Various cleanups and tweaks by Lars, based on feedback
  from several parties.

* 2007-12-01: Initial version written after some quick brainstorming at
  the QA meeting in Extremadura, Spain, by Stefano, Adeodato, and Lars.

1	adeodato	7	[[meta title="DEP-0: Introducing Debian Enhancement Proposals (DEPs)"]]
2
3			Title: Introducing Debian Enhancement Proposals (DEPs)
4			DEP: 0
5			State: DRAFT
6			Date: 2008-01-15
7			Drivers: Stefano Zacchiroli <zack@debian.org>,
8			Adeodato Simó <dato@net.com.org.es>,
9			Lars Wirzenius <liw@iki.fi>
10			URL: http://dep.debian.net/deps/dep0
11			Abstract:
12			Workflow for managing discussions about improvements to Debian and
13			archiving their outcomes.
14
15
16			Introduction
17			------------
18
19			This is a proposal to organize discussions about Debian enhancements,
20			reflect their current status and, in particular, to archive their
21			outcomes, via a new lightweight process based on Debian Enhancement
22			Proposals (DEPs). This idea is loosely based on existing similar systems
23			such as RFCs and Python PEPs. It is also completely opt-in, and does not
24			involve any new committees, powers, or authorities.
25
26
27			Motivation
28			----------
29
30			Currently, when having discussions about improvements to Debian, it is
31			not always clear when consensus has been reached, and people willing to
32			implement it may start too early, leading to wasted efforts, or delay it
33			indefinitely, because there's not clear indication it is time to begin. At the
34			same time, potential adopters of an enhancement may not be able to
35			easily assess whether they should use said implementation or not,
36			because it's difficult to know whether it adjusts to the consensus
37			reached during the discussion period.
38
39			As our normative documents rely on wide adoption of a practice before
40			documenting it, and adopters can be reluctant to make use of it before a
41			clear indication that a practice has some consensus behind it, this
42			creates a hard to break loop that this process hopes to alleviate, by
43			providing a mechanism to reflect the status of each proposal, including
44			whether it has reached consensus or not.
45
46			Secondly, we lack at the moment a central index in which to list such
47			proposals, which would be useful to see at a glance what open fronts
48			there are at a given moment in Debian, and who is taking care of them
49			and, additionally, to serve as a storage place for successfully
50			completed proposals, documenting the outcome of the discussion and the
51			details of the implementation.
52
53			By using this process, people involved in developing any enhancement can
54			help to build such index, with very little overhead required on their
55			part.
56
57
58			Workflow
59			--------
60
61			A "Debian enhancement" can be pretty much any change to Debian,
62			technical or otherwise. Examples of situations when the DEP process
63			might be or might have been used include:
64
65			* Introducing new debian/control fields (Homepage, Vcs-*).
66			* Making debian/copyright be machine parseable.
67			* Agreeing upon a meta-package name or virtual package name.
68			* Deciding on a procedure for the Debconf team for assigning travel
69			sponsorship money.
70			* Formalizing existing informal processes or procedures, e.g.,
71			the procedure for getting a new architecture added to the archive, or
72			getting access to piatti.debian.org to run QA tests.
73
74			The workflow is very simple, and is intended to be quite lightweight:
75			an enhancement to Debian is suggested, discussed, implemented, and
76			becomes accepted practice (or policy, if applicable), in the normal
77			Debian way. As the discussion progresses, the enhancement is assigned
78	adeodato	12	certain states, as explained below. During all the process, a single URL
79	adeodato	7	maintained by the proposers can be used to check the status of the
80			proposal.
81
82			The result of all this is:
83
84			1. an implementation of the enhancement and
85			2. a document that can be referred to later on without having to dig
86			up and read through large discussions.
87
88			The actual discussions should happen in the usual forum or forums for
89			the topic of the DEP. This way, DEPs do not act as yet another forum to
90			be followed. For example, a DEP suggesting changes to www.debian.org
91			graphical design should happen on debian-www, as usual.
92
93			In the same way, DEPs do not give any extra powers or authority to
94			anyone: they rely on reaching consensus in the traditional Debian way,
95			by engaging in discussions on mailing lists, IRC, or real life meetings
96			as appropriate, and not by consulting an external body for a decision.
97			To be acceptable, this consensus includes agreement from affected
98			parties, including those who would have to implement it or accept an
99			implementation.
100
101			The person or people who do the suggestion are the "drivers" of the
102			proposal and have the responsibility of writing the initial draft, and
103			of updating it during the discussions, see below.
104
105
106			Proposal states
107			---------------
108
109			The proposal goes through several states over its lifetime. The ideal
110			progression is DRAFT -> CANDIDATE -> ACCEPTED, but reality requires a
111			couple of other states as well.
112
113			#### DRAFT: discussion until (rough) consensus
114
115			* every new proposal starts as a DRAFT
116			* anyone can propose a draft
117			* each draft has a number (next free one from document index)
118			* normal changes happen in this period
119			* drafts should include extra criteria for success (in addition to
120			having obtained rough consensus, see below), that is, for moving to
121			the ACCEPTED state
122
123			#### CANDIDATE: implementation + testing
124
125			* consensus exists for what should be done, and how it should be done
126			* agreement needs to be expressed by all affected parties, not just the
127			drivers; silence is not agreement, but unanimity is not required, either
128			* implementation can of course start earlier
129			* changes in this period are primarily based on feedback from implementation
130			* this period must be long enough that there is a consensus that the
131			enhancement works (on the basis of implementation evaluation)
132
133			#### ACCEPTED: integrate to policy/devref/elsewhere (if applicable)
134
135			* consensus exists that the implementation has been a success
136			* also, the final version of the document is archived in a central place
137			(vcs on alioth, plus web page generated from that), even if integrated
138			to other documents as well
139
140			#### DROPPED: no further action needed
141
142			* the drivers are no longer interested in pursuing the DEP
143			* if there are no modifications to a DEP in DRAFT state for six months,
144			or there is a consensus that the implementation of a DEP in
145			CANDIDATE state has been abandoned, the DEP is moved to DROPPED
146			state (from which it can be resurrected by moving to DRAFT stage
147			again)
148
149			#### OBSOLETE: no longer relevant
150
151			* for example, when a new revision (as a new DEP) gets accepted, the
152			old one will move to OBSOLETE state, and will be modified to refer
153			to the new one
154
155
156			What the drivers should do
157			--------------------------
158
159			The additional, hopefully small, burden of the DEP process falls on the
160			shoulders of its drivers. They have to take care of all the practical
161			work of writing and maintaining the draft, so that everyone else can
162			just continue discussing things over e-mail as before. Driver's burden
163			can be summarized as:
164
165			* Write the draft.
166			* Update the draft during discussion.
167			* Determine when (rough) consensus in discussion has been reached.
168			* Implement, or find volunteers to implement.
169			* Determine when consensus of implementation success has been reached,
170			when the testing of the available implementation has been satisfactory.
171			* Update the DEP with progress updates at suitable intervals, until the
172			DEP has been accepted.
173
174			If the drivers go missing in action, other people may step in and
175			courteously take over the driving position.
176
177
178			Format and content
179			------------------
180
181			A DEP is basically a free-form plain text file, except that it must
182			start with a paragraph of the following RFC822-style headers:
183
184			* Title: the full title of the document
185			* DEP: the number for this DEP
186			* State: the current state of this revision
187			* Date: the date of this revision
188			* Drivers: a list of drivers (names and e-mail addresses), in RFC822
189			syntax for the To: header
190			* URL: during DRAFT state, a link to the canonical place of the draft
191			(typically probably http://wiki.debian.org/DEP/DEPxxx or
192			http://dep.debian.net/deps/depXXX)
193			* Abstract: a short paragraph (formatted as the long Description in
194			debian/control)
195
196			The rest of the file is free form. If the DEP is kept in a wiki, using
197			its markup syntax is, of course, a good idea.
198
199			Suggested document contents:
200
201			* An introduction, giving an overview of the situation and the motivation
202			for the DEP.
203			* A plan for implementation, especially indicating what parts of Debian need
204			to be changed, and preferably indicating who will do the work.
205			* Preferably a list of criteria to judge whether the implementation has been
206			a success.
207			* Links to mailing list threads, perhaps highlighting particularly important
208			messages. If discussion happens on IRC, pointers to logs would be nice.
209
210
211			Creating a DEP
212			--------------
213
214			The procedure to create a DEP is simple: send an e-mail to
215			`debian-project@lists.debian.org`, stating that you're taking the next
216			available number, and including the first paragraph of the DEP as
217			explained above. It is very important to include the list of drivers,
218			and the URL where the draft will be kept up to date. The next available
219			DEP number can be obtained by consulting <http://dep.debian.net>.
220
221	adeodato	12	It is also a very good idea to mention in this mail the place where the
222			discussion is going to take place, with a pointer to the thread in the
223			mailing list archives if it has already started.
224
225	adeodato	7	Additionally, drivers are welcome to maintain their DEPs, even in the
226			draft state, in a repository inside the `dep` Alioth project, following
227			the instructions at <http://dep.debian.net/howto>. They are free not to
228			do so, and in that case a DEP0 driver or some interested party will
229			update the `dep.debian.net` index with their DEP, and a pointer to the
230			URL they provided.
231
232
233			Revising an accepted DEP
234			------------------------
235
236			If the feature, or whatever, of the DEP needs further changing later,
237			the process can start over with the accepted version of the DEP document
238			as the initial draft. The new draft will get a new DEP number. Once the
239			new DEP is accepted, the old one should move to OBSOLETE state.
240
241
242
243			TODO
244			----
245
246			* Figure out how to mark up a DEP file in wiki.debian.org's syntax
247			in such a way as to make the initial RFC822-style paragraph format
248			sensibly, but without making it require much or any wiki markup.
249			* Mention somewhere explicitly that the location of the index is
250			<http://dep.debian.net>.
251
252
253			Changes
254			-------
255
256			* 2008-01-15:
257			[ Adeodato Simó ]
258			* Add section about how to create a DEP.
259	adeodato	8	* Rewrite "Introduction" (splitting "Motivation" off), and parts of
260			"Workflow" as well.
261	adeodato	7
262			[ Lars Wirzenius ]
263			* Typo fixes.
264
265			* 2008-01-11: Minor tweaks by Zack (mostly cosmetic, but also
266			some more detailed specification of former more vague aspects)
267
268			* 2008-01-09: Various cleanups and tweaks by Lars, based on feedback
269			from several parties.
270
271			* 2007-12-01: Initial version written after some quick brainstorming at
272			the QA meeting in Extremadura, Spain, by Stefano, Adeodato, and Lars.
273