Architectural Decision Records
This is a location to record all architecture decisions in the Oasis Core project via Architectural Decision Records (ADRs).
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>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
masterbranch 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.
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