r7 - in /web: deps/ deps/dep0.mdwn index.mdwn

Wed Jan 16 10:44:18 UTC 2008

Author: adeodato
Date: Wed Jan 16 10:44:18 2008
New Revision: 7

URL: http://svn.debian.org/wsvn/dep/?sc=1&rev=7
Log:
Add dep0.mdwn from http://bzr.debian.org/bzr/dep/dep0/trunk.

Added:
    web/deps/
    web/deps/dep0.mdwn
Modified:
    web/index.mdwn

Added: web/deps/dep0.mdwn
URL: http://svn.debian.org/wsvn/dep/web/deps/dep0.mdwn?rev=7&op=file
==============================================================================

--- web/deps/dep0.mdwn (added)
+++ web/deps/dep0.mdwn Wed Jan 16 10:44:18 2008
@@ -1,0 +1,267 @@
+[[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 at debian.org>,
+     Adeodato SimÃ³ <dato at net.com.org.es>,
+     Lars Wirzenius <liw at 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 at 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.
+
+  [ 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.
+

Modified: web/index.mdwn
URL: http://svn.debian.org/wsvn/dep/web/index.mdwn?rev=7&op=diff
==============================================================================
--- web/index.mdwn (original)
+++ web/index.mdwn Wed Jan 16 10:44:18 2008
@@ -3,4 +3,5 @@
 Debian Enhancement Proposals
 ============================
 
-Foo.
+At the moment, there is only [[deps/dep0]] here. In the future, a full index
+of all DEPs will be provided, together with per-status lists.


