madr
v4.0.0
Published
Markdown Architectural Decision Records
Downloads
37,487
Maintainers
Readme
Markdown Architectural Decision Records
"Markdown Architectural Decision Records" (MADR)
[ˈmæɾɚ]
– decisions that matter[ˈmæɾɚ]
.
For user documentation, please head to https://adr.github.io/madr/.
Quick start
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 https://adr.github.io/madr/#applying-madr-to-your-project.
Development hints
- 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 https://github.com/adr/madr/issues.
- 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 todocs/decisions/adr-template
. However, following YAML front matter is added to make it handled properly by the Just the Docs Jekyll Template.--- parent: Decisions nav_order: 100 title: ADR Template ---
Branches
| 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
.
How to start Jekyll locally
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.
Updating just-the-docs
- Adapt
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. - Delete
docs/Gemfile.lock
. Startbundle install
. - Check https://github.com/just-the-docs/just-the-docs/blob/main/CHANGELOG.md.
- Check https://just-the-docs.com/migration/.
Releasing a new version
- Update the examples at
docs/index.md
anddocs/examples.md
. - Update the concrete decisions in
docs/decisions/*
with the new template. - Commit ("Update examples and decisions") and push. Possibly as pull request.
- Adapt the version reference in
template/0000-use-markdown-architectural-decision-records.md
. - Update "template" files in in
docs/decisions
:- Copy
template/0000-use-markdown-architectural-decision-records.md
todocs/decisions/0000-use-markdown-architectural-decision-records.md
. - Adapt content of
docs/decisions/adr-template.md
based ontemplate/adr-template.md
. Thereby, ensure that the YAML front matter indocs/decisions/adr-template.md
is kept.
- Copy
- Add link to
docs/index.md
at "Older versions" (for the homepage). - Copy
.markdownlint.yml
totemplate/.markdownlint.yml
(and possibly todocs/.markdownlint.yml
). - Update
CHANGELOG.md
. - Commit.
- Update
package.json
and publish to npmjs using release-it (do not create a release on GitHub). This also does a commit. - Create GitHub release using github-release-from-changelog.
- Merge
develop
intogh-pages
License
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