ADR-1: ADR documents specification & process

More details about this document
Latest published version:
https://adr.decentraland.org/adr/ADR-1
Feedback:
GitHub decentraland/adr (pull requests, new issue, open issues)
Edit this documentation:
GitHub View commits View commits on githistory.xyz

What is an ADR?

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.

ADR Rationale

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.

ADR Types

There are three types of ADR:

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.

ADR Work Flow

Shepherding an ADR

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.

ADR Process

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

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 it's 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 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.

What belongs in a successful ADR?

Each ADR should have the following parts:

Picking an ADR number

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.

ADR Formats and Templates

ADRs should be written in markdown format. There is a template to follow.

ADR Header Preamble

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 sentence

description: Description is one full (short) sentence

authors: The list of the author's GitHub username(s).

discussion: The url pointing to the official discussion thread

status: Draft, Review, Last Call, Final, Stagnant, Withdrawn, Living

last-call-deadline: The date last call period ends on (Optional field, only needed when status is Last Call)

type: One of Standards Track, Meta, or ADR

date: Date the ADR was created on

withdrawal-reason: A sentence explaining why the ADR was withdrawn. (Optional field, only needed when status is Withdrawn)

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).

authors header

The authors header lists the GitHub usernames of the authors.

@menduz

discussion header

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).

type header

The type header specifies the type of ADR: Standards Track, Meta, or RFC.

date header

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.

Linking to External Resources

Links to external resources SHOULD NOT be included. External resources may disappear, move, or change unexpectedly.

Linking to other ADRs

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.

Auxiliary Files

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

ADR Editors are defined in the ADR Editors GitHub team.

ADR Editors responsibilities

For each new ADR that comes in, an editor does the following:

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:

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.

Style Guide

Titles

The title field in the preamble:

ADR numbers

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.

RFC 2119 and RFC 8174

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.

History

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

  1. Importance of architecture decisions
  2. Documenting software architectures

License

Copyright and related rights waived via CC0-1.0. DRAFT Living