github.com/ouraigua/jenkins-library@v0.0.0-20231028010029-fbeaf2f3aa9b/documentation/adr/20221004-use-markdown-architectural-decision-records.md (about)

     1  # Use Markdown Architectural Decision Records
     2  
     3  - Status: accepted
     4  - Date: 2022-10-03
     5  - Tags: doc
     6  
     7  ## Context and Problem Statement
     8  
     9  We want to record architectural decisions made in this project.
    10  Which format and structure should these records follow?
    11  
    12  ## Considered Options
    13  
    14  - [MADR](https://adr.github.io/madr/) 2.1.2 with Log4brains patch
    15  - [MADR](https://adr.github.io/madr/) 2.1.2 – The original Markdown Architectural Decision Records
    16  - [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
    17  - [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
    18  - Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
    19  - Formless – No conventions for file format and structure
    20  
    21  ## Decision Outcome
    22  
    23  Chosen option: "MADR 2.1.2 with Log4brains patch", because
    24  
    25  - Implicit assumptions should be made explicit.
    26    Design documentation is important to enable people understanding the decisions later on.
    27    See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
    28  - The MADR format is lean and fits our development style.
    29  - The MADR structure is comprehensible and facilitates usage & maintenance.
    30  - The MADR project is vivid.
    31  - Version 2.1.2 is the latest one available when starting to document ADRs.
    32  - The Log4brains patch adds more features, like tags.
    33  
    34  The "Log4brains patch" performs the following modifications to the original template:
    35  
    36  - Change the ADR filenames format (`NNN-adr-name` becomes `YYYYMMDD-adr-name`), to avoid conflicts during Git merges.
    37  - Add a `draft` status, to enable collaborative writing.
    38  - Add a `Tags` field.
    39  
    40  ## Links
    41  
    42  - Relates to [Use Log4brains to manage the ADRs](20221004-use-log4brains-to-manage-the-adrs.md)