Markdown Architectural Decision Records
npm install madr> "Markdown Architectural Decision Records" (MADR) [ˈmæɾɚ] – decisions that [matter [ˈmæɾɚ]](https://en.wiktionary.org/wiki/matter#Pronunciation).
For user documentation, please head to
* adr-template.md has all sections, with explanations about them.
* adr-template-minmal.md only contains mandatory sections, with explanations about them.
* adr-template-bare.md has all sections, wich are empty (no explanations).
* adr-template-bare-minimal.md has the mandatory sections, without explanations.
Copy it into docs/decisions.
For each ADR, copy the tempalte to nnnn-title.md and adapt.
Longer explanation: Head to
* MADR follows Semantic Versioning 2.0.0 and documents changes in a CHANGELOG.md following keep a changelog 1.0.0.
* Issues can be reported at
* Suggestions can be contributed via pull requests. MADR offers pre-configured VS Code web environment at Gitpod.
* MADR uses markdownlint as Linter for Markdown files. Use markdownlint for checking for linting issues in VS Code.
* template/adr-template.md is mirrored to docs/decisions/adr-template.
However, following YAML front matter is added to make it handled properly by the Just the Docs Jekyll Template.
``markdown`
---
parent: Decisions
nav_order: 100
title: ADR Template
---
| Branch | Meaning |
|--------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| gh-pages | Homepage showing the latest released version, rendered at develop
| | Latest developments, including homepage updates which should be published on a release. gh-pages should always be merged into this branch. |release/vY
| | Branch for latest release Y.x version of MADR. Introduced to fix #92 |
The branch name conventions follow the git flow model.
See also CONTRIBUTING.md.
For rendering the docs directory, Jekyll is needed.
For local development, follow the Jekyll installation instructions.
Installing the latest version of ruby followed by gem install bundler should be enough.
Afterwards, run
`terminal`
bundle install
jekyll serve --livereload
and go to
On Windows, using a dockerized environment is recommended:
`terminal`
docker run -p 4000:4000 --rm -v "C:\git-repositories\adr.github.io\madr\docs":/site bretfisher/jekyll-serve
In case you get errors regarding Gemfile.lock, just delete Gemfile.lock and rerun.
* Adapt docs/Gemfile to use newer just-the-docs version. Thereby check docs/Gemfile.lock
* Delete . Start bundle install.
* Check
* Check
1. Update the examples at docs/index.md and docs/examples.md.docs/decisions/*
2. Update the concrete decisions in with the new template.template/0000-use-markdown-architectural-decision-records.md
3. Commit ("Update examples and decisions") and push. Possibly as pull request.
4. Adapt the version reference in .docs/decisions
5. Update "template" files in in :template/0000-use-markdown-architectural-decision-records.md
* Copy to docs/decisions/0000-use-markdown-architectural-decision-records.md.docs/decisions/adr-template.md
* Adapt content of based on template/adr-template.md.docs/decisions/adr-template.md
Thereby, ensure that the YAML front matter in is kept.docs/index.md
6. Add link to at "Older versions" (for the homepage)..markdownlint.yml
7. Copy to template/.markdownlint.yml (and possibly to docs/.markdownlint.yml).CHANGELOG.md
8. Update .package.json
9. Commit.
10. Update and publish to npmjs using release-it (do not create a release on GitHub). This also does a commit.develop
11. Create GitHub release using github-release-from-changelog.
12. Merge into gh-pages
This work is dual-licensed under MIT and
CC0.
You can choose between one of them if you use this work.
`yaml``
SPDX-License-Identifier: MIT OR CC0-1.0