Skip to content
/ madr Public

Markdown Architectural Decision Records

License

Unknown, MIT licenses found

Licenses found

Unknown
LICENSE
MIT
LICENSE.MIT
Notifications You must be signed in to change notification settings

adr/madr

Repository files navigation

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

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.

Development hints

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

Releasing a new version

  1. Update the examples at docs/index.md and docs/examples.md.
  2. Update the concrete decisions in docs/decisions/* with the new template.
  3. Commit ("Update examples and decisions") and push. Possibly as pull request.
  4. Adapt the version reference in template/0000-use-markdown-architectural-decision-records.md.
  5. Update "template" files in docs/decisions:
    • Copy template/0000-use-markdown-architectural-decision-records.md to docs/decisions/0000-use-markdown-architectural-decision-records.md.
    • Adapt content of docs/decisions/adr-template.md based on template/adr-template.md. Thereby, ensure that the YAML front matter in docs/decisions/adr-template.md is kept.
  6. Add link to docs/index.md at "Older versions" (for the homepage).
  7. Copy .markdownlint.yml to template/.markdownlint.yml (and possibly to docs/.markdownlint.yml).
  8. Update CHANGELOG.md.
  9. Commit.
  10. Update package.json and publish to npmjs using release-it (do not create a release on GitHub). This also does a commit.
  11. Create GitHub release using github-release-from-changelog.
  12. Merge develop into gh-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