34 lines
4.1 KiB
Markdown
34 lines
4.1 KiB
Markdown
|
|
The adr-folder contains Architecture Decision Records.
|
|
An Architecture Decision Record is a file that contains a decision that should be applied to all new and altered code and systems.
|
|
ADR's can only be added or altered on specific request by the user. Agents should never add or modify ADR's without explicit request to do so.
|
|
ADR's are immutable in essence. This means that the only modifications allowed are in its state, or when it applies to typo's, adding clarifications, or removing ambiguity.
|
|
An ADR MUST have the following properties:
|
|
|
|
- ID
|
|
- Title
|
|
- Supersedes
|
|
- Status (NEW, REFINED, APPROVED, REJECTED, EXPIRED)
|
|
- Expiration date
|
|
- Context
|
|
- Decisions
|
|
- Options considered with pro's and cons
|
|
- Consequences.
|
|
An _ID_ MUST be a unique number, prefixed with ADR (e.g. ADR1, ADR2, ADR3, etc.). This makes it easy to reference an ADR.
|
|
A _title_ is a short, unique description of the ADR. It should make it easy to know in a glance what the ADR is about.
|
|
The name of the file SHOULD contain the ID and the title, or a short variant of the title, of the ADR.
|
|
_Supersedes_ is an optional property that MAY reference another, expired ADR that it supersedes.
|
|
When _supersedes_ references another ADR, it MUST do so by referencing its ID.
|
|
When _supersedes_ references another ADR, the status of that other ADR MUST equal to EXPIRED.
|
|
_Status_ contains the state of the ADR. In the readme, when we mention state, we mean the value of this status-property. ADR's are always in a subfolder of the adr-folder, with the same name as the state, but in lowercase ('adr/new' for ADR's with state NEW, 'adr/refined' for ADR's with state REFINED, etc.).
|
|
Each created ADR will start with the state NEW. Apart from the ID and the state, each property can still be modified. Nothing that is in an ADR with state NEW, should be considered when writing or evaluating anything within the software landscape.
|
|
An RFD will get the state REFINED, when it is fully worked out. Only RFD's with the state NEW can be changed to REFINED. This means an effort has been made to get to a final version of the RFD. Getting an RFD from NEW to REFINED can be done with or without the help of an agent. However, an agent should always verify mutual understanding of the content with the human owner, before changing the state from NEW to REFINED.
|
|
An ADR with the state REFINED can be moved to either APPROVED or REJECTED. This step must be done manually, not by any agent. APPROVED means the decision in the ADR applies to all code and/or software added or altered as far as the content of the ADR applies to the situation. Exceptions are possible with explicit accord. Such an accord should be given by a person. REJECTED means that the ADR should not be considered anywhere when writing or evaluating anything within the software landscape.
|
|
An ADR with the state EXPIRED is no longer valid. It should no longer be considered anywhere when writing or evaluating anything within the software landscape, even though it had been the case previously. It MAY have been superseded by a new ADR, but that is not necessary.
|
|
An _expiration date_ indicated from when an ADR should be notified for reevaluation. Reaching the _expiration date_ does not mean the ADR is expired. It only means the ADR should be reevaluated by a person, with or without the help of an agent. As a result of the reevaluation, this ADR may get EXPIRED - only after explicit agreement of a person - and it MAY be superseded by a new one. Another option is that only the expiration date itself gets updated to a new expiration date. This also only after explicit agreement of a person.
|
|
_Context_ should explain the context of the problem where a decision had to be made for.
|
|
The _decision_ describes the decision. This is what all code MUST apply to, unless an explicit exception is approved by a person.
|
|
The _options_ describes the various alternatives that were considered, all with its pro's and con's, and why the chosen decision whas chosen.
|
|
_Consequences_ describes the consequences to the current state of the application landscape at the time of writing. This could be about a migration timeline, a new process, different tooling, or a change in the stack, or something else.
|
|
|