Coder Social home page Coder Social logo

madr's Introduction

Markdown Architectural Decision Records part of ADR

"Markdown Architectural Decision Records" (MADR) [ˈmæɾɚ] – architectural decisions that matter [ˈmæɾɚ].

News

Overview

An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. This might, for instance, be a technology choice (e.g., Java vs. JavaScript), a choice of the IDE (e.g., IntelliJ vs. Eclipse IDE), a choice between a library (e.g., SLF4J vs java.util.logging), or a decision on features (e.g., infinite undo vs. limited undo). Do not take the term "architecture" too seriously or interpret it too strongly. As the examples illustrate, any decisions that might have an impact on the architecture somehow are architectural decisions.

It should be as easy as possible to a) write down the decisions and b) to version the decisions.

This repository offers a solution to record architectural decisions. It provides files to document Architectural Decisions using Markdown and Architectural Decision Records.

Since MADR 3.0.0, the decisions are placed in the folder docs/decisions to

  1. Enable GitHub pages to render it using the web. See https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/ for more information.
  2. Separate the architectural decisions from other documentation.

The filenames are following the pattern NNNN-title-with-dashes.md (ADR-0005), where

  • NNNN is a consecutive number and we assume that there won't be more than 9,999 ADRs in one repository.
  • the title is stored using dashes and lowercase, because adr-tools also does that.
  • the suffix is .md, because it is a Markdown file.

Table of Contents

The Template

The template reads as follows:

# {short title of solved problem and solution}

* Status: {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)} <!-- optional -->
* Deciders: {list everyone involved in the decision} <!-- optional -->
* Date: {YYYY-MM-DD when the decision was last updated} <!-- optional -->

Technical Story: {description | ticket/issue URL} <!-- optional -->

## Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.}

## Decision Drivers <!-- optional -->

* {driver 1, e.g., a force, facing concern, …}
* {driver 2, e.g., a force, facing concern, …}
*<!-- numbers of drivers can vary -->

## Considered Options

* {option 1}
* {option 2}
* {option 3}
*<!-- numbers of options can vary -->

## Decision Outcome

Chosen option: "{option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.

### Positive Consequences <!-- optional -->

* {e.g., improvement of quality attribute satisfaction, follow-up decisions required, …}
*### Negative Consequences <!-- optional -->

* {e.g., compromising quality attribute, follow-up decisions required, …}
*## Pros and Cons of the Options <!-- optional -->

### {option 1}

{example | description | pointer to more information | …} <!-- optional -->

* Good, because {argument a}
* Good, because {argument b}
* Bad, because {argument c}
*<!-- numbers of pros and cons can vary -->

### {option 2}

{example | description | pointer to more information | …} <!-- optional -->

* Good, because {argument a}
* Good, because {argument b}
* Bad, because {argument c}
*<!-- numbers of pros and cons can vary -->

### {option 3}

{example | description | pointer to more information | …} <!-- optional -->

* Good, because {argument a}
* Good, because {argument b}
* Bad, because {argument c}
*<!-- numbers of pros and cons can vary -->

## Links <!-- optional -->

* {Link type} {Link to ADR} <!-- example: Refined by [ADR-0005](0005-example.md) -->
*<!-- numbers of links can vary -->

The template is available at template/adr-template.md.

Example

# Use Markdown Architectural Decision Records

## Context and Problem Statement

We want to record architectural decisions made in this project.
Which format and structure should these records follow?

## Considered Options

* [MADR](https://adr.github.io/madr/) 2.1.0 - The Markdown Architectural Decision Records
* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) - The first incarnation of the term "ADR"
* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) - The Y-Statements
* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
* Formless - No conventions for file format and structure

## Decision Outcome

Chosen option: "MADR 2.1.0", because

* Implicit assumptions should be made explicit.
  Design documentation is important to enable people understanding the decisions later on.
  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
* The MADR format is lean and fits our development style.
* The MADR structure is comprehensible and facilitates usage & maintenance.
* The MADR project is vivid.
* Version 2.1.0 is the latest one available when starting to document ADRs.

The example is rendered at template/0000-use-markdown-architectural-decision-records.md

For the MADR project itself, all ADRs exist at docs/decisions/.

Apply it to your project

Initialization

Create folder docs/decisions in your project. Copy all files in template from the MADR project to the folder docs/decisions in your project.

For instance, using npm, this can be done using the following command:

npm install madr && mkdir -p docs/decisions && cp node_modules/madr/template/* docs/decisions/

Create a new ADR

Manual approach:

  1. Copy adr-template.md to NNNN-title-with-dashes.md, where NNNN indicates the next number in sequence.
  2. Edit NNNN-title-with-dashes.md.
  3. Update index.md, e.g., by executing adr-log -d . You can get adr-log by executing npm install -g adr-log.

Note you can also use other patterns for the directory format, but then the tools cannot be applied.

Automatic approach:

Use our fork of adr-tools. See npryce/adr-tools#43 for the current status of integration.

Development

Releasing a new version:

  1. Update CHANGELOG.md.
  2. Update README.md with the new template and the example.
  3. Adapt the version reference in template/0000-use-markdown-architectural-decision-records.md.
  4. Copy template/0000-use-markdown-architectural-decision-records.md to docs/decisions/0000-use-markdown-architectural-decision-records.md.
  5. Update package.json, publish to npmjs, create GitHub release.
    Use release-it (do not create a release on GitHub) and github-release-from-changelog.

License

License: CC0

madr's People

Contributors

koppor avatar pixelbrackets avatar snisnisniksonah avatar cherouvim avatar timcondit avatar haguenau avatar socadk avatar ms-ati avatar miwurster avatar tomlankhorst avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.