wikimedia/mediawiki-skins-MinervaNeue
1
0
Fork 0
mirror of https://gerrit.wikimedia.org/r/mediawiki/skins/MinervaNeue synced 2024-11-13 17:37:07 +00:00
Code Issues Packages Projects Releases Wiki Activity
mediawiki-skins-MinervaNeue/adr/0001-adopt-adrs.md
Jan Drewniak b0af18ccc6 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
2024-01-29 10:34:28 -05:00

1.9 KiB
Raw Permalink Blame History

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".