| 1 |
[[!meta title="DEP-0: Introducing Debian Enhancement Proposals (DEPs)"]]
|
| 2 |
|
| 3 |
Title: Introducing Debian Enhancement Proposals (DEPs)
|
| 4 |
DEP: 0
|
| 5 |
State: CANDIDATE
|
| 6 |
Date: 2009-07-26
|
| 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 |
License: http://www.jclark.com/xml/copying.txt
|
| 12 |
Abstract:
|
| 13 |
Workflow for managing discussions about improvements to Debian
|
| 14 |
and archiving their outcomes.
|
| 15 |
|
| 16 |
|
| 17 |
Introduction
|
| 18 |
------------
|
| 19 |
|
| 20 |
This is a proposal to organize discussions about Debian enhancements,
|
| 21 |
reflect their current status and, in particular, to archive their
|
| 22 |
outcomes, via a new lightweight process based on Debian Enhancement
|
| 23 |
Proposals (DEPs). This idea is loosely based on existing similar systems
|
| 24 |
such as RFCs and Python PEPs. It is also completely opt-in, and does not
|
| 25 |
involve any new committees, powers, or authorities.
|
| 26 |
|
| 27 |
|
| 28 |
Motivation
|
| 29 |
----------
|
| 30 |
|
| 31 |
Currently, when having discussions about improvements to Debian, it is
|
| 32 |
not always clear when consensus has been reached, and people willing to
|
| 33 |
implement it may start too early, leading to wasted efforts, or delay it
|
| 34 |
indefinitely, because there's not clear indication it is time to begin. At the
|
| 35 |
same time, potential adopters of an enhancement may not be able to
|
| 36 |
easily assess whether they should use said implementation or not,
|
| 37 |
because it's difficult to know whether it adjusts to the consensus
|
| 38 |
reached during the discussion period.
|
| 39 |
|
| 40 |
Our normative documents rely on wide adoption of a practice before
|
| 41 |
documenting it, and adopters can be reluctant to make use of it before a
|
| 42 |
clear indication that a practice has some consensus behind it. This
|
| 43 |
creates a hard to break loop that this process hopes to alleviate, by
|
| 44 |
providing a mechanism to reflect the status of each proposal, including
|
| 45 |
whether it has reached consensus or not.
|
| 46 |
|
| 47 |
Secondly, we lack at the moment a central index in which to list such
|
| 48 |
proposals, which would be useful to see at a glance what open fronts
|
| 49 |
there are at a given moment in Debian, and who is taking care of them
|
| 50 |
and, additionally, to serve as a storage place for successfully
|
| 51 |
completed proposals, documenting the outcome of the discussion and the
|
| 52 |
details of the implementation.
|
| 53 |
|
| 54 |
By using this process, people involved in developing any enhancement can
|
| 55 |
help to build such index, with very little overhead required on their
|
| 56 |
part.
|
| 57 |
|
| 58 |
|
| 59 |
Workflow
|
| 60 |
--------
|
| 61 |
|
| 62 |
A "Debian enhancement" can be pretty much any change to Debian,
|
| 63 |
technical or otherwise. Examples of situations when the DEP process
|
| 64 |
might be or might have been used include:
|
| 65 |
|
| 66 |
* Introducing new debian/control fields (Homepage, Vcs-*).
|
| 67 |
* Making debian/copyright be machine parseable.
|
| 68 |
* Agreeing upon a meta-package name or virtual package name.
|
| 69 |
* Deciding on a procedure for the Debconf team for assigning travel
|
| 70 |
sponsorship money.
|
| 71 |
* Formalizing existing informal processes or procedures, e.g.,
|
| 72 |
the procedure for getting a new architecture added to the archive, or
|
| 73 |
getting access to piatti.debian.org to run QA tests.
|
| 74 |
|
| 75 |
The workflow is very simple, and is intended to be quite lightweight:
|
| 76 |
an enhancement to Debian is suggested, discussed, implemented, and
|
| 77 |
becomes accepted practice (or policy, if applicable), in the normal
|
| 78 |
Debian way. As the discussion progresses, the enhancement is assigned
|
| 79 |
certain states, as explained below. During all the process, a single URL
|
| 80 |
maintained by the proposers can be used to check the status of the
|
| 81 |
proposal.
|
| 82 |
|
| 83 |
The result of all this is:
|
| 84 |
|
| 85 |
1. an implementation of the enhancement and
|
| 86 |
2. a document that can be referred to later on without having to dig
|
| 87 |
up and read through large discussions.
|
| 88 |
|
| 89 |
The actual discussions should happen in the usual forum or forums for
|
| 90 |
the topic of the DEP. This way, DEPs do not act as yet another forum to
|
| 91 |
be followed. For example, a DEP suggesting changes to www.debian.org
|
| 92 |
graphical design should happen on debian-www, as usual.
|
| 93 |
|
| 94 |
In the same way, DEPs do not give any extra powers or authority to
|
| 95 |
anyone: they rely on reaching consensus in the traditional Debian way,
|
| 96 |
by engaging in discussions on mailing lists, IRC, or real life meetings
|
| 97 |
as appropriate, and not by consulting an external body for a decision.
|
| 98 |
To be acceptable, this consensus includes agreement from affected
|
| 99 |
parties, including those who would have to implement it or accept an
|
| 100 |
implementation.
|
| 101 |
|
| 102 |
The person or people who do the suggestion are the "drivers" of the
|
| 103 |
proposal and have the responsibility of writing the initial draft, and
|
| 104 |
of updating it during the discussions, see below.
|
| 105 |
|
| 106 |
|
| 107 |
Proposal states
|
| 108 |
---------------
|
| 109 |
|
| 110 |
<div style="float: right; text-align: center;">
|
| 111 |
[[!img deps/dep0/workflow.png size="500x250" alt="DEP state diagram"]]
|
| 112 |
<br />
|
| 113 |
<span style="font-size: xx-small">DEP workflow: state diagram</span>
|
| 114 |
</div>
|
| 115 |
A given DEP can be in one of the following *states*:
|
| 116 |
|
| 117 |
* DRAFT
|
| 118 |
* CANDIDATE
|
| 119 |
* ACCEPTED
|
| 120 |
* REJECTED
|
| 121 |
* OBSOLETE
|
| 122 |
|
| 123 |
The ideal progression of states is DRAFT -> CANDIDATE -> ACCEPTED, but
|
| 124 |
reality requires a couple of other states and transitions as well.
|
| 125 |
|
| 126 |
### DRAFT state: discussion
|
| 127 |
|
| 128 |
* every new proposal starts as a DRAFT
|
| 129 |
* anyone can propose a draft
|
| 130 |
* each draft has a number (next free one from document index)
|
| 131 |
* normal discussion and changes to the text happen in this state
|
| 132 |
* drafts should include *extra* criteria for success (in addition to
|
| 133 |
having obtained consensus, see below), that is, requirements to
|
| 134 |
finally become ACCEPTED
|
| 135 |
|
| 136 |
#### DRAFT -> CANDIDATE: rough consensus
|
| 137 |
|
| 138 |
In order for a DEP to become CANDIDATE, the following condition should
|
| 139 |
be met:
|
| 140 |
|
| 141 |
* consensus exists for *what* should be done, and *how* it should be
|
| 142 |
done (agreement needs to be expressed by all affected parties, not
|
| 143 |
just the drivers; silence is not agreement, but unanimity is not
|
| 144 |
required, either)
|
| 145 |
|
| 146 |
### CANDIDATE: implementation + testing
|
| 147 |
|
| 148 |
The CANDIDATE state is meant to prove, via a suitable implementation
|
| 149 |
and its testing, that a given DEP is feasible.
|
| 150 |
|
| 151 |
* of course, implementation can start in earlier states
|
| 152 |
* changes to the text can happen also in this period, primarily based
|
| 153 |
on feedback from implementation
|
| 154 |
* this period must be long enough that there is consensus that the
|
| 155 |
enhancement works (on the basis of implementation evaluation)
|
| 156 |
* since DEP are not necessarily technical, "implementation" does not
|
| 157 |
necessarily mean coding
|
| 158 |
|
| 159 |
#### CANDIDATE -> ACCEPTED: working implementation
|
| 160 |
|
| 161 |
In order for a DEP to become ACCEPTED, the following condition should
|
| 162 |
be met:
|
| 163 |
|
| 164 |
* consensus exists that the implementation has been a success
|
| 165 |
|
| 166 |
### ACCEPTED: have fun
|
| 167 |
|
| 168 |
Once accepted:
|
| 169 |
|
| 170 |
* the final version of the DEP text is archived on
|
| 171 |
<http://dep.debian.net> for future reference
|
| 172 |
* if applicable, the proposed DEP change is integrated into
|
| 173 |
authoritative texts such as policy, developer's reference, etc.
|
| 174 |
|
| 175 |
#### {DRAFT, CANDIDATE} -> REJECTED
|
| 176 |
|
| 177 |
A DEP can become REJECTED in the following cases:
|
| 178 |
|
| 179 |
* the drivers are no longer interested in pursuing the DEP and
|
| 180 |
explicitly acknowledge so
|
| 181 |
* there are no modifications to a DEP in DRAFT state for 6 months or
|
| 182 |
more
|
| 183 |
* there is no consensus either on the draft text or on the fact that
|
| 184 |
the implementation is working satisfactorily
|
| 185 |
|
| 186 |
#### ACCEPTED -> OBSOLETE: no longer relevant
|
| 187 |
|
| 188 |
A DEP can become OBSOLETE when it is no longer relevant, for example:
|
| 189 |
|
| 190 |
* a new DEP gets accepted overriding previous DEPs (in that case the
|
| 191 |
new DEP should refer to the one it OBSOLETE-s)
|
| 192 |
* the object of the enhancement is no longer in use
|
| 193 |
|
| 194 |
### {REJECTED, OBSOLETE}
|
| 195 |
|
| 196 |
In one of these states, no further actions are needed.
|
| 197 |
|
| 198 |
It is recommended that DEPs in one of these states carry a reason
|
| 199 |
describing why they have moved to such a state.
|
| 200 |
|
| 201 |
|
| 202 |
What the drivers should do
|
| 203 |
--------------------------
|
| 204 |
|
| 205 |
The only additional burden of the DEP process falls on the shoulders of its
|
| 206 |
drivers. They have to take care of all the practical work of writing
|
| 207 |
and maintaining the text, so that everyone else can just continue
|
| 208 |
discussing things as before. Driver's burden can be summarized as:
|
| 209 |
|
| 210 |
* Write the draft text and update it during discussion.
|
| 211 |
* Determine when (rough) consensus in discussion has been reached.
|
| 212 |
* Implement, or find volunteers to implement.
|
| 213 |
* Determine when consensus of implementation success has been reached,
|
| 214 |
when the testing of the available implementation has been satisfactory.
|
| 215 |
* Update the DEP with progress updates at suitable intervals, until the
|
| 216 |
DEP has been accepted (or rejected).
|
| 217 |
|
| 218 |
If the drivers go missing in action, other people may step in and
|
| 219 |
courteously take over the driving position.
|
| 220 |
|
| 221 |
**Note**: the drivers can of course participate in the discussion as
|
| 222 |
everybody else, but have no special authority to impose their ideas to
|
| 223 |
others. <q>DEP gives pencils, not hammers.</q>
|
| 224 |
|
| 225 |
|
| 226 |
Format and content
|
| 227 |
------------------
|
| 228 |
|
| 229 |
A DEP is basically a free-form plain text file, except that it must
|
| 230 |
start with a paragraph of the following RFC822-style headers:
|
| 231 |
|
| 232 |
* Title: the full title of the document
|
| 233 |
* DEP: the number for this DEP
|
| 234 |
* State: the current state of this revision
|
| 235 |
* Date: the date of this revision
|
| 236 |
* Drivers: a list of drivers (names and e-mail addresses), in RFC822
|
| 237 |
syntax for the To: header
|
| 238 |
* URL: during DRAFT state, a link to the canonical place of the draft
|
| 239 |
(typically probably http://wiki.debian.org/DEP/DEPxxx or
|
| 240 |
http://dep.debian.net/deps/depXXX)
|
| 241 |
* Abstract: a short paragraph (formatted as the long Description in
|
| 242 |
debian/control)
|
| 243 |
|
| 244 |
(Additionally, REJECTED DEPs can carry a "Reason:" field describing
|
| 245 |
why they were rejected.)
|
| 246 |
|
| 247 |
The rest of the file is free form. If the DEP is kept in a wiki, using
|
| 248 |
its markup syntax is, of course, a good idea.
|
| 249 |
|
| 250 |
Suggested document contents:
|
| 251 |
|
| 252 |
* An introduction, giving an overview of the situation and the motivation
|
| 253 |
for the DEP.
|
| 254 |
* A plan for implementation, especially indicating what parts of Debian need
|
| 255 |
to be changed, and preferably indicating who will do the work.
|
| 256 |
* Preferably a list of criteria to judge whether the implementation has been
|
| 257 |
a success.
|
| 258 |
* Links to mailing list threads, perhaps highlighting particularly important
|
| 259 |
messages. If discussion happens on IRC, pointers to logs would be nice.
|
| 260 |
|
| 261 |
|
| 262 |
License
|
| 263 |
-------
|
| 264 |
|
| 265 |
The DEP must have a license that is DFSG free. You may choose the
|
| 266 |
license freely, but the "Expat" license is recommended. The
|
| 267 |
official URL for it is <http://www.jclark.com/xml/copying.txt> and
|
| 268 |
the license text is:
|
| 269 |
|
| 270 |
Copyright (c) <year> <your names>
|
| 271 |
|
| 272 |
Permission is hereby granted, free of charge, to any person obtaining
|
| 273 |
a copy of this software and associated documentation files (the
|
| 274 |
"Software"), to deal in the Software without restriction, including
|
| 275 |
without limitation the rights to use, copy, modify, merge, publish,
|
| 276 |
distribute, sublicense, and/or sell copies of the Software, and to
|
| 277 |
permit persons to whom the Software is furnished to do so, subject to
|
| 278 |
the following conditions:
|
| 279 |
|
| 280 |
The above copyright notice and this permission notice shall be included
|
| 281 |
in all copies or substantial portions of the Software.
|
| 282 |
|
| 283 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
| 284 |
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
| 285 |
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
| 286 |
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
| 287 |
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
| 288 |
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
| 289 |
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
| 290 |
|
| 291 |
The justification for this recommendation is that this license is one
|
| 292 |
of the most permissive of the well-known licenses. By using this
|
| 293 |
license, it is easy to copy parts of the DEP to other places, such as
|
| 294 |
documentation for Debian development or embedded in individual
|
| 295 |
packages.
|
| 296 |
|
| 297 |
|
| 298 |
|
| 299 |
Creating a DEP
|
| 300 |
--------------
|
| 301 |
|
| 302 |
The procedure to create a DEP is simple: send an e-mail to
|
| 303 |
`debian-project@lists.debian.org`, stating that you're taking the next
|
| 304 |
available number, and including the first paragraph of the DEP as
|
| 305 |
explained above. It is very important to include the list of drivers,
|
| 306 |
and the URL where the draft will be kept up to date. The next available
|
| 307 |
DEP number can be obtained by consulting <http://dep.debian.net>.
|
| 308 |
|
| 309 |
It is also a very good idea to mention in this mail the place where the
|
| 310 |
discussion is going to take place, with a pointer to the thread in the
|
| 311 |
mailing list archives if it has already started.
|
| 312 |
|
| 313 |
Additionally, drivers are welcome to maintain their DEPs, even in the
|
| 314 |
draft state, in a repository inside the `dep` Alioth project, following
|
| 315 |
the instructions at <http://dep.debian.net/depdn-howto>. They are free not to
|
| 316 |
do so, and in that case a DEP0 driver or some interested party will
|
| 317 |
update the `dep.debian.net` index with their DEP, and a pointer to the
|
| 318 |
URL they provided.
|
| 319 |
|
| 320 |
|
| 321 |
Revising an accepted DEP
|
| 322 |
------------------------
|
| 323 |
|
| 324 |
If the feature, or whatever, of the DEP needs further changing later,
|
| 325 |
the process can start over with the accepted version of the DEP document
|
| 326 |
as the initial draft. The new draft will get a new DEP number. Once the
|
| 327 |
new DEP is accepted, the old one should move to OBSOLETE state.
|
| 328 |
|
| 329 |
|
| 330 |
|
| 331 |
License
|
| 332 |
-------
|
| 333 |
|
| 334 |
The following copyright statement and license apply to DEP0 (this
|
| 335 |
document).
|
| 336 |
|
| 337 |
Copyright (c) 2008-2009 Stefano Zacchiroli, Adeodato Simó, Lars Wirzenius
|
| 338 |
|
| 339 |
Permission is hereby granted, free of charge, to any person obtaining
|
| 340 |
a copy of this software and associated documentation files (the
|
| 341 |
"Software"), to deal in the Software without restriction, including
|
| 342 |
without limitation the rights to use, copy, modify, merge, publish,
|
| 343 |
distribute, sublicense, and/or sell copies of the Software, and to
|
| 344 |
permit persons to whom the Software is furnished to do so, subject to
|
| 345 |
the following conditions:
|
| 346 |
|
| 347 |
The above copyright notice and this permission notice shall be included
|
| 348 |
in all copies or substantial portions of the Software.
|
| 349 |
|
| 350 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
| 351 |
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
| 352 |
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
| 353 |
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
| 354 |
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
| 355 |
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
| 356 |
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
| 357 |
|
| 358 |
Changes
|
| 359 |
-------
|
| 360 |
|
| 361 |
* 2009-07-26:
|
| 362 |
[ Zack, Dato, Lars]
|
| 363 |
* Re-word state description: describe separately states and
|
| 364 |
transitions.
|
| 365 |
* Rename "DROPPED" status to "REJECTED"; inhibit "resurrection" of
|
| 366 |
REJECTED DEPs.
|
| 367 |
* Mention that dep.debian.net is the central archival place
|
| 368 |
* Stress that DEPs give no special powers to drivers, in the "driver
|
| 369 |
role" section
|
| 370 |
* Change the state of DEP0 to CANDIDATE
|
| 371 |
|
| 372 |
* 2008-06-12:
|
| 373 |
[ Lars Wirzenius ]
|
| 374 |
* Added a recommendation for the Expat license for new DEPs.
|
| 375 |
* Set this DEP to be licensed under the Expat license.
|
| 376 |
|
| 377 |
* 2008-05-29:
|
| 378 |
[ Lars Wirzenius ]
|
| 379 |
* Added section saying that a DEP should have a DFSG free license.
|
| 380 |
|
| 381 |
* 2008-01-15:
|
| 382 |
[ Adeodato Simó ]
|
| 383 |
* Add section about how to create a DEP.
|
| 384 |
* Rewrite "Introduction" (splitting "Motivation" off), and parts of
|
| 385 |
"Workflow" as well.
|
| 386 |
|
| 387 |
[ Lars Wirzenius ]
|
| 388 |
* Typo fixes.
|
| 389 |
|
| 390 |
* 2008-01-11: Minor tweaks by Zack (mostly cosmetic, but also
|
| 391 |
some more detailed specification of former more vague aspects)
|
| 392 |
|
| 393 |
* 2008-01-09: Various cleanups and tweaks by Lars, based on feedback
|
| 394 |
from several parties.
|
| 395 |
|
| 396 |
* 2007-12-01: Initial version written after some quick brainstorming at
|
| 397 |
the QA meeting in Extremadura, Spain, by Stefano, Adeodato, and Lars.
|
| 398 |
|
Parent Directory
| 
Revision Log