{"id":13820446,"url":"https://github.com/adr/madr","last_synced_at":"2025-05-13T17:08:53.557Z","repository":{"id":22883983,"uuid":"97574655","full_name":"adr/madr","owner":"adr","description":"Markdown Architectural Decision Records","archived":false,"fork":false,"pushed_at":"2025-03-31T22:22:36.000Z","size":390,"stargazers_count":1653,"open_issues_count":22,"forks_count":423,"subscribers_count":25,"default_branch":"develop","last_synced_at":"2025-04-24T07:55:44.446Z","etag":null,"topics":["architectural-decision-records","architectural-decisions","design-document","design-documents","documentation","hacktoberfest"],"latest_commit_sha":null,"homepage":"https://adr.github.io/madr/","language":"Markdown","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-07-18T08:37:12.000Z","updated_at":"2025-04-23T13:52:10.000Z","dependencies_parsed_at":"2024-03-12T10:31:03.726Z","dependency_job_id":"8e6050f0-d30c-42f3-afbf-77e6eb53a562","html_url":"https://github.com/adr/madr","commit_stats":{"total_commits":214,"total_committers":19,"mean_commits":"11.263157894736842","dds":"0.16355140186915884","last_synced_commit":"11212731c0ff65ecb42b68625fcc6a27d285a1a3"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fmadr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fmadr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fmadr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fmadr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adr","download_url":"https://codeload.github.com/adr/madr/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250835363,"owners_count":21495141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architectural-decision-records","architectural-decisions","design-document","design-documents","documentation","hacktoberfest"],"created_at":"2024-08-04T08:01:03.523Z","updated_at":"2025-04-25T14:40:52.431Z","avatar_url":"https://github.com/adr.png","language":"Markdown","readme":"# Markdown Architectural Decision Records\n\n\u003e \"Markdown Architectural Decision Records\" (MADR) `[ˈmæɾɚ]` – decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation).\n\nFor user documentation, please head to \u003chttps://adr.github.io/madr/\u003e.\n\n## Quick start\n\n* [`adr-template.md`](template/adr-template.md) has all sections, with explanations about them.\n* [`adr-template-minimal.md`](template/adr-template-minimal.md) only contains mandatory sections, with explanations about them. \u003c!-- ### Consequences also contained, though marked as \"optional\" --\u003e\n* [`adr-template-bare.md`](template/adr-template-bare.md) has all sections, which are empty (no explanations).\n* [`adr-template-bare-minimal.md`](template/adr-template-bare-minimal.md) has the mandatory sections, without explanations. \u003c!-- ### Consequences also contained, though marked as \"optional\" --\u003e\n\nCopy it into `docs/decisions`.\nFor each ADR, copy the template to `nnnn-title.md` and adapt.\nLonger explanation: Head to \u003chttps://adr.github.io/madr/#applying-madr-to-your-project\u003e.\n\n## Development hints\n\n* 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/).\n* Issues can be reported at \u003chttps://github.com/adr/madr/issues\u003e.\n* 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).\n* MADR uses [markdownlint](https://github.com/DavidAnson/markdownlint) as Linter for Markdown files. Use [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) for checking for linting issues in VS Code.\n* `template/adr-template.md` is mirrored to `docs/decisions/adr-template`.\n  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/). \u003c!-- markdownlint-disable-next-line MD031 --\u003e\n  ```markdown\n  ---\n  parent: Decisions\n  nav_order: 100\n  title: ADR Template\n  ---\n  ```\n\n### Branches\n\n| Branch       | Meaning                                                                                                                                      |\n|--------------|----------------------------------------------------------------------------------------------------------------------------------------------|\n| `gh-pages`   | Homepage showing the latest released version, rendered at \u003chttps://adr.github.io/madr\u003e                                                       |\n| `develop`    | Latest developments, including homepage updates which should be published on a release. `gh-pages` should always be merged into this branch. |\n| `release/vY` | Branch for latest release Y.x version of MADR. Introduced to fix [#92](https://github.com/adr/madr/issues/92)                                |\n\nThe branch name conventions follow the [git flow model](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow).\n\nSee also [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## How to start Jekyll locally\n\nFor rendering the `docs` directory, Jekyll is needed.\n\nFor local development, follow the [Jekyll installation instructions](https://jekyllrb.com/docs/installation/).\nInstalling the latest version of ruby followed by `gem install bundler` should be enough.\n\nAfterwards, run\n\n```terminal\nbundle install\njekyll serve --livereload\n```\n\nand go to \u003chttp://localhost:4000/madr/\u003e in your browser.\n\nOn Windows, using a dockerized environment is recommended:\n\n```terminal\ndocker run -p 4000:4000 --rm -v \"C:\\git-repositories\\adr.github.io\\madr\\docs\":/site bretfisher/jekyll-serve\n```\n\nIn case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and rerun.\n\n## Updating just-the-docs\n\n* Adapt `docs/Gemfile` to use newer just-the-docs version. Thereby check \u003chttps://github.com/just-the-docs/just-the-docs-template/blob/main/Gemfile\u003e for versions.\n* Delete `docs/Gemfile.lock`. Start `bundle install`.\n* Check \u003chttps://github.com/just-the-docs/just-the-docs/blob/main/CHANGELOG.md\u003e.\n* Check \u003chttps://just-the-docs.com/migration/\u003e.\n\n## Releasing a new version\n\n1. Update the examples at `docs/index.md` and `docs/examples.md`.\n2. Update the concrete decisions in `docs/decisions/*` with the new template.\n3. Commit (\"Update examples and decisions\") and push. Possibly as pull request.\n4. Adapt the version reference in `template/0000-use-markdown-architectural-decision-records.md`.\n5. Update \"template\" files in `docs/decisions`:\n   * Copy `template/0000-use-markdown-architectural-decision-records.md` to `docs/decisions/0000-use-markdown-architectural-decision-records.md`.\n   * Adapt content of `docs/decisions/adr-template.md` based on `template/adr-template.md`.\n     Thereby, ensure that the YAML front matter in `docs/decisions/adr-template.md` is kept.\n6. Add link to `docs/index.md` at \"Older versions\" (for the homepage).\n7. Copy `.markdownlint.yml` to `template/.markdownlint.yml` (and possibly to `docs/.markdownlint.yml`).\n8. Update `CHANGELOG.md`.\n9. Commit.\n10. 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.\n11. Create GitHub release using [github-release-from-changelog](https://www.npmjs.com/package/github-release-from-changelog).\n12. Merge `develop` into `gh-pages`\n\n## License\n\nThis work is dual-licensed under [MIT](https://opensource.org/licenses/MIT) and\n[CC0](https://creativecommons.org/share-your-work/public-domain/cc0/).\nYou can choose between one of them if you use this work.\n\n```yaml\nSPDX-License-Identifier: MIT OR CC0-1.0\n```\n","funding_links":[],"categories":["Decision Records (ADR/RFC)","Markdown","🎨 Design \u0026 Creative","Others","hacktoberfest"],"sub_categories":["Design Patterns"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadr%2Fmadr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadr%2Fmadr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadr%2Fmadr/lists"}