Skip to content

Latest commit

 

History

History
119 lines (92 loc) · 4.89 KB

README.md

File metadata and controls

119 lines (92 loc) · 4.89 KB
Raw

Architectural Decision Records

This is a location to record all architecture decisions in the Oasis Core project via Architectural Decision Records (ADRs).

Format

Each record has a unique number associated with it to make it easier to cross-reference them. The records are stored as Markdown files in this directory, named using the following convention:

<adr-number>-<short-title>.md

Where:

  • <adr-number> is the assigned zero-padded ADR number.
  • <short-title> is the ADR's title in Kebab case.

The content of each ADR should follow the template. In short, an ADR should provide:

  • a changelog of all modifications so far,
  • context on the relevant goals and the current state,
  • proposed changes to achieve the goals,
  • summary of pros and cons,
  • references and
  • the decision that was made.

Process for Creating New ADRs

There is a lightweight process for proposing, discussing and deciding on ADRs:

  • Create branch: If you have write permissions to the repository, you can create user-id prefixed branches (e.g. user/feature/foobar) in the main repository. Otherwise, fork the main repository and create your branches there.

    • Good habit: regularly rebase to the HEAD of master branch of the main repository to make sure you prevent nasty conflicts:

      git rebase <main-repo>/master

    • Push your branch to GitHub regularly so others can see what you are working on:

      git push -u <main-repo-or-your-fork> <branch-name>

      Note that you are allowed to force push into your development branches.

  • Use draft pull requests for work-in-progress:

    • The draft state signals that the code is not ready for review, but still gives a nice URL to track the ongoing work.

  • In your branch, create a new ADR file following the convention and template specified above.

  • Update the index of current records below.

  • Create a pull request and mark it as ready for review. The commit message for introducing an ADR should have the title of the ADR, following by a short summary:

    ADR 0000: Architectural Decision Records

Introduce architectural decision records (ADRs) for keeping track of
architecture decisions in a transparent way.

  • The ADR will be discussed by other members of the community and the project committers. After a sufficient amount of discussion, acceptance or rejection decision will be taken in accoordance with the governance process and the pull request will be merged, introducing a new ADR.

After the ADR is merged an implementation may be undertaken by following the contribution process.

Current Records

The following records currently exist:

  • ADR 0000 - Architectural Decision Records
  • ADR 0001 - Multiple Roots Under the Tendermint Application Hash
  • ADR 0002 - Go Modules Compatible Git Tags
  • ADR 0003 - Consensus/Runtime Token Transfer
  • ADR 0004 - Runtime Governance
  • ADR 0005 - Runtime Compute Node Slashing
  • ADR 0006 - Consensus Governance
  • ADR 0007 - Improved Random Beacon
  • ADR 0008 - Standard Account Key Generation
  • ADR 0009 - Ed25519 Signature Verification Semantics
  • ADR 0010 - VRF-based Committee Elections
  • ADR 0011 - Incoming Runtime Messages
  • ADR 0012 - Runtime Message Results
  • ADR 0013 - Runtime Upgrade Improvements
  • ADR 0014 - Signing Runtime Transactions with Hardware Wallet
  • ADR 0015 - Randomized Paratime Proposer Selection
  • ADR 0016 - Consensus Parameters Change Proposal
  • ADR 0020 - Governance Support for Delegator Votes
  • ADR 0021 - Forward-Secret Ephemeral Secrets
  • ADR 0022 - Forward-Secret Master Secrets
  • ADR 0024 - Runtime Off-chain Logic (ROFL)