github.com/Tri-stone/burrow@v0.25.0/docs/ADRs/adr-1.md (about)

     1  ---
     2  adr: 1
     3  title: ADR Purpose and Guidelines
     4  discussions-to: https://chat.hyperledger.org/channel/burrow-contributors
     5  status: Draft
     6  type: Meta
     7  author: The Burrow's marmots and others
     8          https://github.com/hyperledger/burrow/ADRs/blob/master/ADRs/adr-1.md
     9  created: 2018-10-09
    10  ---
    11  
    12  ## What is an ADR?
    13  
    14  ADR stands for Architecture Decision Record.
    15  An ADR is a design document providing information to the Burrow community, or describing a new feature for Burrow or its processes or environment.
    16  The ADR should provide a concise technical specification of the feature and a rationale for the feature.
    17  The ADR author is responsible for building consensus within the community and documenting dissenting opinions.
    18  
    19  ![burrow logo](../assets/adr-1/burrow-logo.png)
    20  
    21  ## ADR Rationale
    22  
    23  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 Burrow. Because the ADRs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.
    24  
    25  ## ADR Formats and Templates
    26  
    27  ADRs should be written in [markdown] format.
    28  Image files should be included in a subdirectory of the `assets` folder for that ADR as follow: `assets/adr-X` (for adr **X**). When linking to an image in the ADR, use relative links such as `../assets/adr-X/image.png`.
    29  
    30  ## ADR Header Preamble
    31  
    32  Each ADR must begin with an RFC 822 style header preamble, preceded and followed by three hyphens (`---`). The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required.
    33  
    34  ` adr:` <ADR number>
    35  
    36  ` title:` <ADR title>
    37  
    38  ` author:` <a list of the author's or authors' name(s) and/or username(s), or name(s) and email(s). Details are below.>
    39  
    40  ` * discussions-to:` \<a url pointing to the official discussion thread\>
    41  
    42   - :x: `discussions-to` can not be a Github `Pull-Request`.
    43  
    44  ` status:` <Draft | Last Call | Accepted | Final | Active | Deferred | Rejected | Superseded>
    45  
    46  `* review-period-end:` YYYY-MM-DD
    47  
    48  ` type:` <Standards Track (Accounts and State, Consensus, Crypto, EVM, Gateway)  | Informational | Meta>
    49  
    50  ` * category:` <Accounts and State | Consensus | Crypto | EVM | Gateway>
    51  
    52  ` created:` <date created on, in ISO 8601 (yyyy-mm-dd) format>
    53  
    54  ` * requires:` <ADR number(s)>
    55  
    56  ` * replaces:` <ADR number(s)>
    57  
    58  ` * superseded-by:` <ADR number(s)>
    59  
    60  ` * resolution:` \<a url pointing to the resolution of this ADR\>
    61  
    62  #### Author header
    63  
    64  The author header optionally lists the names, email addresses or usernames of the authors/owners of the ADR. Those who prefer anonymity may use a username only, or a first name and a username. The format of the author header value must be:
    65  
    66  Random J. User &lt;address@dom.ain&gt;
    67  
    68  or
    69  
    70  Random J. User (@username)
    71  
    72  if the email address or GitHub username is included, and
    73  
    74  Random J. User
    75  
    76  if the email address is not given.
    77  
    78  Note: The resolution header is required for Standards Track ADRs only. It contains a URL that should point to an email message or other web resource where the pronouncement about the ADR is made.
    79  
    80  While an ADR is a draft, a discussions-to header will indicate the mailing list or URL where the ADR is being discussed.
    81  
    82  The type header specifies the type of ADR: Standards Track, Meta, or Informational. If the track is Standards please include the subcategory (core, networking, consensus, or EVM).
    83  
    84  The category header specifies the ADR's category. This is required for standards-track ADRs only.
    85  
    86  The created header records the date that the ADR was assigned a number. Both headers should be in yyyy-mm-dd format, e.g. 2001-08-14.
    87  
    88  ADRs may have a requires header, indicating the ADR numbers that this ADR depends on.
    89  
    90  ADRs may also have a superseded-by header indicating that an ADR has been rendered obsolete by a later document; the value is the number of the ADR that replaces the current document. The newer ADR must have a Replaces header containing the number of the ADR that it rendered obsolete.
    91  
    92  Headers that permit lists must separate elements with commas.
    93  
    94  ## History
    95  
    96  This document was derived heavily from [Ethereum's EIP1] written by Martin Becze and Hudson Jameson which in turn was derived from [Bitcoin's ADR-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, they are not responsible for its use in the Burrow Improvement Process, and should not be bothered with technical questions specific to Burrow or the ADR. Please direct all comments to the ADR editors.
    97  
    98  This document was inspired from [ADR GitHub Organization](https://adr.github.io/) and [ADR Examples](https://github.com/joelparkerhenderson/architecture_decision_record).