"Markdown Architectural Decision Records" (MADR)
[ˈmæɾɚ]
– decisions that matter[ˈmæɾɚ]
.
For user documentation, please head to https://adr.github.io/madr/.
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, which 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 template to nnnn-title.md
and adapt.
Longer explanation: Head to https://adr.github.io/madr/#applying-madr-to-your-project.
CHANGELOG.md
following keep a changelog 1.0.0.template/adr-template.md
is mirrored to docs/decisions/adr-template
.---
parent: Decisions
nav_order: 100
title: ADR Template
---
Branch | Meaning |
---|---|
gh-pages |
Homepage showing the latest released version, rendered at https://adr.github.io/madr |
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
bundle install
jekyll serve --livereload
and go to http://localhost:4000/madr/ in your browser.
On Windows, using a dockerized environment is recommended:
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.
docs/Gemfile
to use newer just-the-docs version. Thereby check https://github.com/just-the-docs/just-the-docs-template/blob/main/Gemfile for versions.docs/Gemfile.lock
. Start bundle install
.docs/index.md
and docs/examples.md
.docs/decisions/*
with the new template.template/0000-use-markdown-architectural-decision-records.md
.docs/decisions
:
template/0000-use-markdown-architectural-decision-records.md
to docs/decisions/0000-use-markdown-architectural-decision-records.md
.docs/decisions/adr-template.md
based on template/adr-template.md
.docs/decisions/adr-template.md
is kept.docs/index.md
at "Older versions" (for the homepage)..markdownlint.yml
to template/.markdownlint.yml
(and possibly to docs/.markdownlint.yml
).CHANGELOG.md
.package.json
and publish to npmjs using release-it (do not create a release on GitHub). This also does a commit.develop
into gh-pages
This work is dual-licensed under MIT and CC0. You can choose between one of them if you use this work.
SPDX-License-Identifier: MIT OR CC0-1.0