Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://adr.github.io/madr/
Markdown Architectural Decision Records
https://adr.github.io/madr/
architectural-decision-records architectural-decisions design-document design-documents documentation hacktoberfest
Last synced: about 2 months ago
JSON representation
Markdown Architectural Decision Records
- Host: GitHub
- URL: https://adr.github.io/madr/
- Owner: adr
- License: other
- Created: 2017-07-18T08:37:12.000Z (over 7 years ago)
- Default Branch: develop
- Last Pushed: 2024-10-16T12:06:11.000Z (2 months ago)
- Last Synced: 2024-10-18T01:15:00.093Z (2 months ago)
- Topics: architectural-decision-records, architectural-decisions, design-document, design-documents, documentation, hacktoberfest
- Language: Markdown
- Homepage: https://adr.github.io/madr/
- Size: 343 KB
- Stars: 1,421
- Watchers: 24
- Forks: 402
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-architecture - Markdown Architectural Decision Records
README
# Markdown Architectural Decision Records
> "Markdown Architectural Decision Records" (MADR) `[ˈmæɾɚ]` – decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation).
For user documentation, please head to .
## Development hints
* MADR follows [Semantic Versioning 2.0.0](https://semver.org/) and documents changes in a `CHANGELOG.md` following [keep a changelog 1.0.0](http://keepachangelog.com/en/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](https://gitpod.io/#https://github.com/adr/madr).
* Use [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
* `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](https://just-the-docs.github.io/just-the-docs/).
```markdown
---
parent: Decisions
nav_order: 100
title: ADR Template
---
```
### Branches
| 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/v1` | Branch for latest release 1.x version of MADR. Introduced to fix [#92](https://github.com/adr/madr/issues/92) |
| `release/vY` | Branch for version Y.x of MADR. |
## How to start Jekyll locally
For rendering the `docs` directory, Jekyll is needed.
For local development, follow the [Jekyll installation instructions](https://jekyllrb.com/docs/installation/).
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 in your browser.
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.
## Updating just-the-docs
* Adapt `docs/Gemfile` to use newer just-the-docs version. Thereby check for versions.
* Delete `docs/Gemfile.lock`. Start `bundle install`.
* Check .
* Check .
## 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-madr.md`.
5. Update "template" files in in `docs/decisions/`
* Copy `template/0000-use-madr.md` to `docs/decisions/0000-use-madr.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. Update `CHANGELOG.md`.
8. Copy `.markdownlint.yml` to `template/.markdownlint.yml`
9. Update `package.json` and publish to [npmjs](https://www.npmjs.com/package/madr) using [release-it](https://www.npmjs.com/package/release-it) (do not create a release on GitHub). This also does a commit.
10. Create GitHub release using [github-release-from-changelog](https://www.npmjs.com/package/github-release-from-changelog).
11. Merge `develop` into `gh-pages`
## License
This work is dual-licensed under [MIT](https://opensource.org/licenses/MIT) and
[CC0](https://creativecommons.org/share-your-work/public-domain/cc0/).
You can choose between one of them if you use this work.
```yaml
SPDX-License-Identifier: MIT OR CC0-1.0
```