| adr | date | title | status | type | spdx-license |
|---|---|---|---|---|---|
1 |
2020-10-05 |
ADR documents specification & process |
Living |
Meta |
CC0-1.0 |
ADR stands for Architecture Decision Record. An ADR is a design document providing information to the Decentraland community, or describing a new feature for Decentraland or its processes or environment. The ADR should provide a concise technical specification of the feature and a rationale for the feature. The ADR author is responsible for building consensus within the community and documenting dissenting opinions.
ADRs are heavily inspired in Ethereum Improvement Proposals (EIPs).
We intend ADRs to be the primary mechanisms for proposing new features, for collecting community technical input on an issue, and for documenting the design decisions that have gone into Decentraland. Because the ADRs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.
For Decentraland implementers, ADRs are a convenient way to track the progress of their implementation. Ideally each implementation maintainer would list the ADRs that they have implemented. This will give end users a convenient way to know the current status of a given implementation or library.
There are three types of ADR:
-
A Standards Track ADR describes any change that affects most or all Decentraland implementations, such as—a change to the synchronization protocol, a change in deployments validity rules, proposed application standards/conventions, or any change or addition that affects the interoperability of applications using Decentraland. Standards Track ADRs consist of three parts—a design document, an implementation, and (if warranted) an update to the formal specification.
-
A Meta ADR describes a process surrounding Decentraland or proposes a change to (or an event in) a process. Process ADRs are like Standards Track ADRs but apply to areas other than the Decentraland protocol itself.
-
An RFC describes a Decentraland design issue, or provides general guidelines or information to the Decentraland community. RFCs do not necessarily represent Decentraland community consensus or a recommendation, so users and implementers are free to ignore RFCs or follow their advice.
It is highly recommended that a single ADR contain a single key proposal or new idea. The more focused the ADR, the more successful it tends to be.
An ADR must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the protocol unduly.
Before you begin writing a formal ADR, you should vet your idea. Ask the Decentraland community first if an idea is original to avoid wasting time on something that will be rejected based on prior research. It is thus recommended to open a discussion thread on the ADR discussions to do this.
Once the idea has been vetted, your next responsibility will be to present (by means of an ADR) the idea to the reviewers and all interested parties, invite editors, developers, and the community to give feedback on the aforementioned channels. You should try and gauge whether the interest in your ADR is commensurate with both the work involved in implementing it and how many parties will have to conform to it.
The following is the standardization process for all ADRs in all tracks:
flowchart TB
Draft --> Withdrawn
Idea --> Draft
Draft --> Review
Review <--> Living
Review <--> LastCall
LastCall --> Final
Review --> Withdrawn
LastCall --> Withdrawn
LastCall <--> Stagnant
Review <--> Stagnant
Draft <--> Stagnant
Final --> Deprecated
Living --> Deprecated
Idea - An idea that is pre-draft. This is not tracked within the ADR Repository as a text file, it is recommended to start with an issue or discussion.
Draft - The first formally tracked stage of an ADR in development. An ADR is merged by an ADR Editor into the ADR repository when properly formatted.
Review - An ADR Author marks an ADR as ready for and requesting Peer Review.
Last Call - This is the final review window for an ADR before moving to Final. An ADR editor will assign Last Call status and set a review end date (last-call-deadline), typically 14 days later.
If this period results in necessary normative changes it will revert the ADR to Review.
Final - This ADR represents the final standard. A Final ADR exists in a state of finality and should only be updated to correct errata and add non-normative clarifications.
Stagnant - Any ADR in Draft or Review or Last Call if inactive for a period of 6 months or greater is moved to Stagnant. An ADR may be resurrected from this state by Authors or ADR Editors through moving it back to Draft or its earlier status. If not resurrected, a proposal may stay forever in this status.
Withdrawn - The ADR Author(s) have withdrawn the proposed ADR. This state has finality and can no longer be resurrected using this ADR number. If the idea is pursued at a later date it is considered a new proposal.
Living - A special status for ADRs that are designed to be continually updated and not reach a state of finality. This includes most notably ADR-1.
Deprecated - An ADR that was previously marked as Final and implemented but has become obsolete or no longer relevant due to protocol or feature changes. Deprecated ADRs must include a Deprecation Reason explaining their obsolescence and, where applicable, link to newer ADRs that supersede them.
Each ADR should have the following parts:
- Preamble - RFC 822 style headers containing metadata about the ADR, including the ADR number, a short descriptive title (limited to a maximum of 44 characters), a description (limited to a maximum of 140 characters), and the author details. Irrespective of the category, the title and description should not include ADR number.
- Abstract - Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the document section. Someone should be able to read only the abstract to get the gist of what this document is about in its current state. Abstracts should be always up to date with the current state of the document.
- Context, Reach & Prioritization - Go into detail about the subject in question. Why is this decision important? The urgency of the decision? Datapoints and related background information. Vocabulary and key terms.
- Solution Space Exploration - Discuss the potential alternatives and their impact. What alternatives are being considered, their benefits, their costs (team resources, money, time frames), and mitigations for any drawbacks.
- Specification - The technical specification should describe the syntax and semantics of any new feature.
The initial issue number or the pull request number that adds the file to the decentraland/adr MUST be used as the final ADR number. This will ensure not having number conflicts in "wip" pull requests.
ADRs should be written in markdown format. There is a template to follow.
Each ADR must begin with an RFC 822 style header preamble, preceded and followed by three hyphens (---). This header is also termed "front matter" by Jekyll. The headers must appear in the following order.
adr: ADR number (this is determined by the ADR editor)title: The ADR title is a few words, not a complete sentencedescription: Description is one full (short) sentenceauthors: The list of the author's GitHub username(s).discussion: The url pointing to the official discussion threadstatus: Draft, Review, Last Call, Final, Stagnant, Withdrawn, Living, Deprecatedlast-call-deadline: The date last call period ends on (Optional field, only needed when status isLast Call)type: One ofStandards Track,Meta, orADRdate: Date the ADR was created onwithdrawal-reason: A sentence explaining why the ADR was withdrawn. (Optional field, only needed when status isWithdrawn)deprecated-reason: A sentence explaining why the ADR was deprecated. (Optional field, only needed when status isDeprecated)
Headers that permit lists must separate elements with commas.
Headers requiring dates will always do so in the format of ISO 8601 (yyyy-mm-dd).
The authors header lists the GitHub usernames of the authors.
@menduz
While an ADR is a draft, a discussion header will indicate the URL where the ADR is being discussed.
The preferred discussion URL is an issue or discussion on the ADR repository. The URL cannot point to Github pull requests, any URL which is ephemeral, and any URL which can get locked over time (i.e. Reddit topics).
The type header specifies the type of ADR: Standards Track, Meta, or RFC.
The date header records the date that the ADR was assigned a number. Both headers should be in yyyy-mm-dd format, e.g. 2020-02-20.
Links to external resources SHOULD NOT be included. External resources may disappear, move, or change unexpectedly.
References to other ADRs should follow the format ADR-N where N is the ADR number you are referring to. Each ADR that is referenced in an ADR MUST be accompanied by an absolute markdown link to the absolute rendered path i.e. /adr/ADR-1.
Images, diagrams and auxiliary files should be included in a subdirectory of the public/resources folder for that ADR as follows: public/resources/ADR-N (where N is to be replaced with the ADR number). When linking to an image in the ADR public/resources, use absolute links such as /resources/ADR-1/image.png.
ADR Editors are defined in the ADR Editors GitHub team.
For each new ADR that comes in, an editor does the following:
- Read the ADR to check if it is ready: sound and complete. The ideas must make technical sense, even if they don’t seem likely to get to final status.
- The title should accurately describe the content.
- Check the ADR for language (spelling, grammar, sentence structure, etc.), markup (GitHub flavored Markdown), code style
If the ADR isn’t ready, the editor will send it back to the author for revision, with specific instructions.
Once the ADR is ready for the repository, the ADR editor will:
- Assign an ADR number (generally the PR number, but the decision is with the editors)
- Merge the corresponding pull request
- Send a message back to the ADR author with the next step.
Many ADRs are written and maintained by developers with write access to the Decentraland codebase. The ADR editors monitor ADR changes, and correct any structure, grammar, spelling, or markup mistakes they see.
The editors don’t pass judgment on ADRs. They merely do the administrative & editorial part.
The title field in the preamble:
- Should not include the word "standard" or any variation thereof; and
- Should not include the ADR's number.
When referring to an ADR by number, it should be written in the hyphenated form ADR-X where X is the ADR's assigned number.
ADRs are encouraged to follow RFC 2119 and RFC 8174 for terminology and to insert the following at the beginning of the Specification section:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
This document was derived heavily from Ethereum EIPs which was also derived from Bitcoin's BIP-0001 written by Amir Taaki which in turn was derived from Python's PEP-0001. In many places text was simply copied and modified. Although the PEP-0001 text was written by Barry Warsaw, Jeremy Hylton, and David Goodger.
The initial document for ADRs for Decentraland can be found in the git history of this file and it was derived from Documenting Architecture Decisions by Michael Nygard.
- Added
DeprecatedStatus:- Introduced the
Deprecatedstatus to identify ADRs that were previously marked asFinalbut are now obsolete due to changes in Decentraland's architecture, protocol, or feature set. - Deprecated ADRs must include a
deprecated-reasonexplaining their obsolescence and, if applicable, link to newer ADRs that supersede them. - More details https://adr.decentraland.org/adr/ADR-277
- Introduced the