mirror of
https://github.com/thunderbird/thunderbird-android.git
synced 2024-09-20 04:02:14 +02:00
Add ADR readme and template
This commit is contained in:
parent
1cb9a37625
commit
950b9d7ba5
10
README.md
10
README.md
@ -44,6 +44,16 @@ Any contributions, large or small, major features, bug fixes, unit/integration t
|
||||
but will be thoroughly reviewed and discussed.
|
||||
Please make sure you read the [Code Style Guidelines](https://github.com/thundernest/k-9/wiki/CodeStyle).
|
||||
|
||||
### Architecture Decision Records (ADR)
|
||||
|
||||
We use [Architecture Decision Records](https://adr.github.io/) to document the architectural decisions made in the
|
||||
development of K-9 Mail. You can find them in the [`docs/architecture/adr`](docs/architecture/adr) directory.
|
||||
|
||||
For more information about our ADRs, please see the [ADRs README](docs/architecture/adr/README.md).
|
||||
|
||||
We encourage team members and contributors to read through our ADRs to understand the architectural decisions that
|
||||
have shaped this project so far. Feel free to propose new ADRs or suggest modifications to existing ones as needed.
|
||||
|
||||
## Communication
|
||||
|
||||
Aside from discussing changes in [pull requests](https://github.com/thundernest/k-9/pulls) and
|
||||
|
29
docs/architecture/adr/0000-adr-template.md
Normal file
29
docs/architecture/adr/0000-adr-template.md
Normal file
@ -0,0 +1,29 @@
|
||||
# [NNNN] - [Descriptive Title in Title Case]
|
||||
|
||||
## Status
|
||||
|
||||
<!-- [Status from the options: proposed, accepted, rejected, deprecated, superseded] -->
|
||||
|
||||
- **Status**
|
||||
|
||||
## Context
|
||||
|
||||
<!-- [Description of the context and problem statement that the decision is addressing. It should contain any relevant factors that influenced the decision.] -->
|
||||
|
||||
## Decision
|
||||
|
||||
<!-- [Description of the decision that was made. Detail the change that will be implemented.] -->
|
||||
|
||||
## Consequences
|
||||
|
||||
<!-- [Explanation of the consequences of the decision. This includes both the positive and negative effects, and any potential risks.] -->
|
||||
|
||||
- **Positive Consequences**
|
||||
|
||||
- consequence 1
|
||||
- consequence 2
|
||||
|
||||
- **Negative Consequences**
|
||||
|
||||
- consequence 1
|
||||
- consequence 2
|
51
docs/architecture/adr/README.md
Normal file
51
docs/architecture/adr/README.md
Normal file
@ -0,0 +1,51 @@
|
||||
# Architecture Decision Records
|
||||
|
||||
This [folder](/docs/architecture/adr) contains the architecture decision records (ADRs) for our project.
|
||||
|
||||
ADRs are short text documents that serve as a historical context for the architecture decisions we make over the
|
||||
course of the project.
|
||||
|
||||
## What is an ADR?
|
||||
|
||||
An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along
|
||||
with its context and consequences. ADRs record the decision making process and allow others to understand the
|
||||
rationale behind decisions, providing insight and facilitating future decision-making processes.
|
||||
|
||||
## Format of an ADR
|
||||
|
||||
We adhere to Michael Nygard's [ADR format proposal](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions),
|
||||
where each ADR document should contain:
|
||||
|
||||
1. **Title**: A short descriptive name for the decision.
|
||||
2. **Status**: The current status of the decision (proposed, accepted, rejected, deprecated, superseded)
|
||||
3. **Context**: The context that motivates this decision.
|
||||
4. **Decision**: The change that we're proposing and/or doing.
|
||||
5. **Consequences**: What becomes easier or more difficult to do and any risks introduced as a result of the decision.
|
||||
|
||||
## Creating a new ADR
|
||||
|
||||
When creating a new ADR, please follow the provided [ADR template file](0000-adr-template.md) and ensure that your
|
||||
document is clear and concise.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
The ADRs will be stored in a directory named `docs/adr`, and each ADR will be a file named `NNNN-title-with-dashes.md`
|
||||
where `NNNN` is a four-digit number that is increased by 1 for every new adr.
|
||||
|
||||
## ADR Life Cycle
|
||||
|
||||
The life cycle of an ADR is as follows:
|
||||
|
||||
1. **Proposed**: The ADR is under consideration.
|
||||
2. **Accepted**: The decision described in the ADR has been accepted and should be adhered to, unless it is superseded by another ADR.
|
||||
3. **Rejected**: The decision described in the ADR has been rejected.
|
||||
4. **Deprecated**: The decision described in the ADR is no longer relevant due to changes in system context.
|
||||
5. **Superseded**: The decision described in the ADR has been replaced by another decision.
|
||||
|
||||
Each ADR will have a status indicating its current life-cycle stage. An ADR can be updated over time, either to change
|
||||
the status or to add more information.
|
||||
|
||||
## Contributions
|
||||
|
||||
We welcome contributions in the form of new ADRs or updates to existing ones. Please ensure all contributions follow
|
||||
the standard format and provide clear and concise information.
|
Loading…
Reference in New Issue
Block a user