Architectural Decision Records for CoreOS/Atomic Unification in Fedora

To learn about ADRs:

• https://martinfowler.com/bliki/ArchitectureDecisionRecord.html
• https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

How to use this repository

You can either directly add your ADR, or you can use the adr CLI at https://github.com/npryce/adr-tools.

Manual creation

1. Copy template.md to the records directory.
2. Name the file using the convention ####-descriptive-title.md. The number should be consecutive after the last ADR listed.

How to write the doc

1. Update the title to match the new name of the file.
2. Update the date to the current date when you are writing the proposal.
3. Status should be pending until it is accepted and about to be merged in.
4. Complete the rest of the document as thoroughly as possible, but keep it reasonably short and precise (~1-2 pages, usually, depending on the complexity of the decision).
5. Use diagrams as needed! Mermaid works well in this context.
6. Commit the document to a new branch and open a pull request to the repo.

How to review and merge

1. Use the built-in review tools to review the proposed document, and follow agreed-upon review rules.
2. The document may ultimately be merged as accepted. If it is rejected, close the PR with no further updates. If, for some reason, the team decides that it is important to save the rejected proposal, open a new document to accept with the rejection and rationale rather than saving a rejected document to avoid confusion.

How to reverse or supersede a document

To reverse a decision, change the status to reversed. To supersede a decision, change the status to superseded in the same PR as the new ADR is proposed.

Questions? Reach out to the team in our Matrix channel.