mirror of
https://gerrit.wikimedia.org/r/mediawiki/skins/MinervaNeue
synced 2024-11-23 22:03:39 +00:00
Adopt ADRs (architectural decision records)
Adds the first ADR to the MinervaNeue skin. The file is placed in a top-level `/adr` folder since the `/doc` folder is already used for auto-generated documentation. Change-Id: I83ad4a1bf8e81caaea9312d4c3efc3bf5ce419be
This commit is contained in:
parent
6ae120b2be
commit
b0af18ccc6
53
adr/0001-adopt-adrs.md
Normal file
53
adr/0001-adopt-adrs.md
Normal file
|
@ -0,0 +1,53 @@
|
|||
# 1. Adopt ADRs (Architectural decision records)
|
||||
|
||||
Date: 2024-01-29
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
|
||||
Options:
|
||||
- Proposed - If a decision is still pending acceptance.
|
||||
- Accepted - If a decision has been accepted by the maintaining team.
|
||||
- Deprecated - If a decision is no longer relevant.
|
||||
- Superseded - If a decision has been replaced with a newer one. Should include
|
||||
link to the newer ADR.
|
||||
|
||||
## Context
|
||||
|
||||
As the code and teams maintaining this repository change over time, the
|
||||
knowledge of why certain decisions were made in the past may be lost or poorly
|
||||
understood. In order to help future maintainers of this repository (as well as
|
||||
our future selves) make sense of this code, we need to keep records of any
|
||||
significant, atypical or otherwise notable decisions.
|
||||
|
||||
Since architectural decisions are made gradually, these records should be easily
|
||||
editable and added incrementally as changes arise.
|
||||
|
||||
## Decision
|
||||
|
||||
We will adopt architecture decision records. This file serves as a template for
|
||||
ADRs. ADRs will be numbered markdown files placed in the /adr directory.
|
||||
The format will follow the Michael Nygard ARD style as described on the
|
||||
following web page:
|
||||
|
||||
https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html
|
||||
|
||||
More guidance on how to write ADRS:
|
||||
https://adr.github.io/
|
||||
|
||||
## Consequences
|
||||
|
||||
When any important, atypical or otherwise notable decision is made within this
|
||||
codebase, an ADR should be created and placed inside this directory. It is up to
|
||||
the person with the most context to create the ADR with regards to that decision.
|
||||
The ADR should be brief and may link to Phabricator or other places that hold
|
||||
more context around the decision.
|
||||
|
||||
ADRs may also be used to propose changes by framing the ADR as a proposal and
|
||||
marking the status as "proposed". If there is agreement to adopt the ADR, it's
|
||||
status should be change to "accepted".
|
||||
|
||||
ADRs can also be marked "deprecated" or "superseded".
|
||||
|
||||
|
Loading…
Reference in a new issue