[[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 , Adeodato Simó , Lars Wirzenius 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 . 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 . 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 . 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.