RFC: Introducing Debian Enhancement Proposals (DEPs)
Hi,
Lars Wirzenius, Stefano Zacchiroli and myself are trying to introduce
the concept of Debian Enhancement Proposals, which I had in mind for
many months until purely by chance, in the Extremadura QA meeting last
December, I brought it up to Lars, and together with Zack we produced an
initial draft. After some feedback on that draft and some later work, we
are now bringing it up for discussion here.
The idea is simple and certainly not new, but we all thought it'd be
good for Debian to have something like this, once tailored to Debian's
own peculiarities. The goals we're aiming to are:
1. having clear indication of the status of ongoing proposals,
particularly to settle that a certain design/implementation has
been agreed upon, ensuring that time spent in that implementation
will not by wasted, and dissipating "fears" of adopting such
implementation (which should help to break the traditional "wide
adoption vs normative documents" Debian loop)
2. having a central place/mechanism to document decisions and
consensus reached in our traditional ways and forums, to which we
can later refer to instead of "yeah, *that* mailing list thread"
While writing the draft, we've tried to do things in a way that will
adjust to the Debian way (TM). The draft is below. Now we'd like to
receive feedback to improve it, and achieve consensus that it's good
enough to try the idea with some real world examples. (Note that after
that, and per the DEP0 text itself, it can be modified some more.)
-8<-
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 explaned 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>.
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.
->8-
--
Adeodato Simó dato at net.com.org.es
Debian Developer adeodato at debian.org
Reply to: