| 1 |
[[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 |
certain states, as explaned below. During all the process, a single URL
|
| 79 |
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 |
Additionally, drivers are welcome to maintain their DEPs, even in the
|
| 222 |
draft state, in a repository inside the `dep` Alioth project, following
|
| 223 |
the instructions at <http://dep.debian.net/howto>. They are free not to
|
| 224 |
do so, and in that case a DEP0 driver or some interested party will
|
| 225 |
update the `dep.debian.net` index with their DEP, and a pointer to the
|
| 226 |
URL they provided.
|
| 227 |
|
| 228 |
|
| 229 |
Revising an accepted DEP
|
| 230 |
------------------------
|
| 231 |
|
| 232 |
If the feature, or whatever, of the DEP needs further changing later,
|
| 233 |
the process can start over with the accepted version of the DEP document
|
| 234 |
as the initial draft. The new draft will get a new DEP number. Once the
|
| 235 |
new DEP is accepted, the old one should move to OBSOLETE state.
|
| 236 |
|
| 237 |
|
| 238 |
|
| 239 |
TODO
|
| 240 |
----
|
| 241 |
|
| 242 |
* Figure out how to mark up a DEP file in wiki.debian.org's syntax
|
| 243 |
in such a way as to make the initial RFC822-style paragraph format
|
| 244 |
sensibly, but without making it require much or any wiki markup.
|
| 245 |
* Mention somewhere explicitly that the location of the index is
|
| 246 |
<http://dep.debian.net>.
|
| 247 |
|
| 248 |
|
| 249 |
Changes
|
| 250 |
-------
|
| 251 |
|
| 252 |
* 2008-01-15:
|
| 253 |
[ Adeodato Simó ]
|
| 254 |
* Add section about how to create a DEP.
|
| 255 |
* Rewrite "Introduction" (splitting "Motivation" off), and parts of
|
| 256 |
"Workflow" as well.
|
| 257 |
|
| 258 |
[ Lars Wirzenius ]
|
| 259 |
* Typo fixes.
|
| 260 |
|
| 261 |
* 2008-01-11: Minor tweaks by Zack (mostly cosmetic, but also
|
| 262 |
some more detailed specification of former more vague aspects)
|
| 263 |
|
| 264 |
* 2008-01-09: Various cleanups and tweaks by Lars, based on feedback
|
| 265 |
from several parties.
|
| 266 |
|
| 267 |
* 2007-12-01: Initial version written after some quick brainstorming at
|
| 268 |
the QA meeting in Extremadura, Spain, by Stefano, Adeodato, and Lars.
|
| 269 |
|
Parent Directory
| 
Revision Log