├── .editorconfig ├── .gitattributes ├── .github ├── dependabot.yml └── workflows │ ├── check-links.yaml │ ├── lint.yaml │ └── pages.yaml ├── .gitignore ├── .gitpod.yml ├── .lycheeignore ├── .makrdownlint-cli2.yml ├── .markdownlint.yml ├── .release-it.json ├── .vscode ├── extensions.json └── ltex.dictionary.en-US.txt ├── CHANGELOG.md ├── CONTRIBUTING.md ├── LICENSE ├── LICENSE.CC0-1.0 ├── LICENSE.MIT ├── README.md ├── docs ├── .ruby-version ├── Dockerfile ├── Gemfile ├── Gemfile.lock ├── README.md ├── _config.yml ├── _sass │ └── color_schemes │ │ └── adr.scss ├── decisions │ ├── .markdownlint.yml │ ├── 0000-use-markdown-architectural-decision-records.md │ ├── 0001-use-CC0-or-MIT-as-license.md │ ├── 0002-do-not-use-numbers-in-headings.md │ ├── 0003-provide-own-madr-tools.md │ ├── 0004-write-own-toc-tool.md │ ├── 0005-use-dashes-in-filenames.md │ ├── 0006-use-names-as-identifier.md │ ├── 0007-do-not-emphasize-line-headings.md │ ├── 0008-add-status-field.md │ ├── 0008-example-badge.png │ ├── 0008-example-separate-heading.png │ ├── 0008-example-table.png │ ├── 0009-support-links-between-adrs-inside-an-adrs.md │ ├── 0010-support-categories.md │ ├── 0011-use-asterisk-as-list-marker.md │ ├── 0012-use-curly-braces-to-denote-placeholder.md │ ├── 0013-example.png │ ├── 0013-use-yaml-front-matter-for-meta-data.md │ ├── 0014-allow-neutral-arguments.md │ ├── 0015-include-consulting-informed-of-raci.md │ ├── 0016-outcome-before-detailed-pros-cons.md │ ├── 0017-use-same-format-for-outcomes-and-options.md │ ├── 0018-use-confirmation-as-heading.md │ ├── adr-template.md │ └── index.md ├── examples.md ├── index.md └── tooling.md ├── package.json └── template ├── .markdownlint.yml ├── 0000-use-markdown-architectural-decision-records.md ├── README.md ├── adr-template-bare-minimal.md ├── adr-template-bare.md ├── adr-template-minimal.md ├── adr-template.md └── i18n └── de └── adr-template.md /.editorconfig: -------------------------------------------------------------------------------- 1 | # This file is for unifying the coding style for different editors and IDEs 2 | # editorconfig.org 3 | 4 | root = true 5 | 6 | [*] 7 | end_of_line = lf 8 | charset = utf-8 9 | trim_trailing_whitespace = true 10 | insert_final_newline = true 11 | indent_style = space 12 | indent_size = 2 13 | 14 | [*.md] 15 | trim_trailing_whitespace = false 16 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=auto eol=lf 2 | *.md linguist-documentation=false 3 | *.md linguist-detectable 4 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | directory: "/" 5 | schedule: 6 | interval: "weekly" 7 | -------------------------------------------------------------------------------- /.github/workflows/check-links.yaml: -------------------------------------------------------------------------------- 1 | name: Check external href links 2 | 3 | on: 4 | pull_request: 5 | push: 6 | paths: 7 | - '.github/workflows/check-links.yml' 8 | - '**/*.md' 9 | schedule: 10 | - cron: "0 9 1 * *" 11 | workflow_dispatch: 12 | 13 | concurrency: 14 | group: "${{ github.workflow }}-${{ github.head_ref }}" 15 | cancel-in-progress: true 16 | 17 | jobs: 18 | lychee: 19 | runs-on: ubuntu-latest 20 | steps: 21 | - uses: actions/checkout@v4 22 | with: 23 | show-progress: 'false' 24 | - name: Restore lychee cache 25 | uses: actions/cache@v4 26 | with: 27 | path: .lycheecache 28 | key: cache-lychee-${{ github.sha }} 29 | restore-keys: cache-lychee- 30 | - name: Link Checker 31 | id: lychee 32 | uses: lycheeverse/lychee-action@v2.4.1 33 | with: 34 | fail: true 35 | args: --max-concurrency 1 --cache --no-progress --exclude-all-private './**/*.md' 36 | -------------------------------------------------------------------------------- /.github/workflows/lint.yaml: -------------------------------------------------------------------------------- 1 | name: Lint 2 | on: 3 | push: 4 | branches: 5 | - develop 6 | - release/* 7 | pull_request: 8 | merge_group: 9 | workflow_dispatch: 10 | jobs: 11 | lint: 12 | runs-on: ubuntu-latest 13 | steps: 14 | - name: Set up Git repository 15 | uses: actions/checkout@v4 16 | - name: Lint 17 | uses: DavidAnson/markdownlint-cli2-action@v20 18 | with: 19 | globs: | 20 | *.md, 21 | docs/**/*.md 22 | template/0000-use-markdown-architectural-decision-records.md 23 | template/adr-template-minimal.md 24 | template/adr-template.md 25 | template/README.md 26 | changelog: 27 | name: CHANGELOG.md 28 | runs-on: ubuntu-latest 29 | steps: 30 | - name: Checkout source 31 | uses: actions/checkout@v4 32 | - name: Lint CHANGELOG.md 33 | run: | 34 | # Install jbang 35 | curl -Ls https://sh.jbang.dev | bash -s - app setup 36 | export PATH=$PATH:$HOME/.jbang/bin 37 | 38 | # run heylogs verification 39 | jbang com.github.nbbrd.heylogs:heylogs-cli:0.9.2:bin check CHANGELOG.md > heylogs.txt || true 40 | 41 | # improve output 42 | # sed -i 's/all-h2-contain-a-version/all-h2-contain-a-version (ignored)/' heylogs.txt 43 | 44 | cat heylogs.txt 45 | 46 | # exit 1 in case of error 47 | grep -q "No problem" heylogs.txt || exit 1 48 | -------------------------------------------------------------------------------- /.github/workflows/pages.yaml: -------------------------------------------------------------------------------- 1 | name: Deploy Jekyll site to Pages 2 | 3 | on: 4 | push: 5 | paths: 6 | - 'docs/**' 7 | - '.github/workflows/pages.yml' 8 | workflow_dispatch: 9 | 10 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 11 | permissions: 12 | contents: read 13 | pages: write 14 | id-token: write 15 | 16 | # Allow one concurrent deployment 17 | concurrency: 18 | group: ${{ github.workflow }}-${{ github.ref }} 19 | cancel-in-progress: true 20 | 21 | jobs: 22 | build: 23 | runs-on: ubuntu-latest 24 | steps: 25 | - name: Checkout 26 | uses: actions/checkout@v4 27 | with: 28 | show-progress: '' 29 | - name: Setup Ruby 30 | uses: ruby/setup-ruby@v1 31 | with: 32 | ruby-version: '3.1' # Not needed with a .ruby-version file 33 | bundler-cache: true # runs 'bundle install' and caches installed gems automatically 34 | cache-version: 0 # Increment this number if you need to re-download cached gems 35 | - name: Setup Pages 36 | id: pages 37 | uses: actions/configure-pages@v5 38 | - name: Build with Jekyll 39 | # Outputs to the './_site' directory by default 40 | run: | 41 | cd docs 42 | bundle install 43 | bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" --destination "../_site" 44 | env: 45 | JEKYLL_ENV: production 46 | - name: Upload artifact 47 | uses: actions/upload-pages-artifact@v3 48 | 49 | deploy: 50 | if: github.ref == 'refs/heads/gh-pages' 51 | environment: 52 | name: github-pages 53 | url: ${{ steps.deployment.outputs.page_url }} 54 | runs-on: ubuntu-latest 55 | needs: build 56 | steps: 57 | - name: Deploy to GitHub Pages 58 | id: deployment 59 | uses: actions/deploy-pages@v4 60 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | package-lock.json 2 | 3 | # Created by https://www.toptal.com/developers/gitignore/api/vim,macos,linux,emacs,eclipse,windows,intellij+all,jekyll 4 | # Edit at https://www.toptal.com/developers/gitignore?templates=vim,macos,linux,emacs,eclipse,windows,intellij+all,jekyll 5 | 6 | ### Eclipse ### 7 | .metadata 8 | bin/ 9 | tmp/ 10 | *.tmp 11 | *.bak 12 | *.swp 13 | *~.nib 14 | local.properties 15 | .settings/ 16 | .loadpath 17 | .recommenders 18 | 19 | # External tool builders 20 | .externalToolBuilders/ 21 | 22 | # Locally stored "Eclipse launch configurations" 23 | *.launch 24 | 25 | # PyDev specific (Python IDE for Eclipse) 26 | *.pydevproject 27 | 28 | # CDT-specific (C/C++ Development Tooling) 29 | .cproject 30 | 31 | # CDT- autotools 32 | .autotools 33 | 34 | # Java annotation processor (APT) 35 | .factorypath 36 | 37 | # PDT-specific (PHP Development Tools) 38 | .buildpath 39 | 40 | # sbteclipse plugin 41 | .target 42 | 43 | # Tern plugin 44 | .tern-project 45 | 46 | # TeXlipse plugin 47 | .texlipse 48 | 49 | # STS (Spring Tool Suite) 50 | .springBeans 51 | 52 | # Code Recommenders 53 | .recommenders/ 54 | 55 | # Annotation Processing 56 | .apt_generated/ 57 | .apt_generated_test/ 58 | 59 | # Scala IDE specific (Scala & Java development for Eclipse) 60 | .cache-main 61 | .scala_dependencies 62 | .worksheet 63 | 64 | # Uncomment this line if you wish to ignore the project description file. 65 | # Typically, this file would be tracked if it contains build/dependency configurations: 66 | #.project 67 | 68 | ### Eclipse Patch ### 69 | # Spring Boot Tooling 70 | .sts4-cache/ 71 | 72 | ### Emacs ### 73 | # -*- mode: gitignore; -*- 74 | *~ 75 | \#*\# 76 | /.emacs.desktop 77 | /.emacs.desktop.lock 78 | *.elc 79 | auto-save-list 80 | tramp 81 | .\#* 82 | 83 | # Org-mode 84 | .org-id-locations 85 | *_archive 86 | 87 | # flymake-mode 88 | *_flymake.* 89 | 90 | # eshell files 91 | /eshell/history 92 | /eshell/lastdir 93 | 94 | # elpa packages 95 | /elpa/ 96 | 97 | # reftex files 98 | *.rel 99 | 100 | # AUCTeX auto folder 101 | /auto/ 102 | 103 | # cask packages 104 | .cask/ 105 | dist/ 106 | 107 | # Flycheck 108 | flycheck_*.el 109 | 110 | # server auth directory 111 | /server/ 112 | 113 | # projectiles files 114 | .projectile 115 | 116 | # directory configuration 117 | .dir-locals.el 118 | 119 | # network security 120 | /network-security.data 121 | 122 | 123 | ### Intellij+all ### 124 | # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider 125 | # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 126 | 127 | # User-specific stuff 128 | .idea/**/workspace.xml 129 | .idea/**/tasks.xml 130 | .idea/**/usage.statistics.xml 131 | .idea/**/dictionaries 132 | .idea/**/shelf 133 | 134 | # AWS User-specific 135 | .idea/**/aws.xml 136 | 137 | # Generated files 138 | .idea/**/contentModel.xml 139 | 140 | # Sensitive or high-churn files 141 | .idea/**/dataSources/ 142 | .idea/**/dataSources.ids 143 | .idea/**/dataSources.local.xml 144 | .idea/**/sqlDataSources.xml 145 | .idea/**/dynamic.xml 146 | .idea/**/uiDesigner.xml 147 | .idea/**/dbnavigator.xml 148 | 149 | # Gradle 150 | .idea/**/gradle.xml 151 | .idea/**/libraries 152 | 153 | # Gradle and Maven with auto-import 154 | # When using Gradle or Maven with auto-import, you should exclude module files, 155 | # since they will be recreated, and may cause churn. Uncomment if using 156 | # auto-import. 157 | # .idea/artifacts 158 | # .idea/compiler.xml 159 | # .idea/jarRepositories.xml 160 | # .idea/modules.xml 161 | # .idea/*.iml 162 | # .idea/modules 163 | # *.iml 164 | # *.ipr 165 | 166 | # CMake 167 | cmake-build-*/ 168 | 169 | # Mongo Explorer plugin 170 | .idea/**/mongoSettings.xml 171 | 172 | # File-based project format 173 | *.iws 174 | 175 | # IntelliJ 176 | out/ 177 | 178 | # mpeltonen/sbt-idea plugin 179 | .idea_modules/ 180 | 181 | # JIRA plugin 182 | atlassian-ide-plugin.xml 183 | 184 | # Cursive Clojure plugin 185 | .idea/replstate.xml 186 | 187 | # SonarLint plugin 188 | .idea/sonarlint/ 189 | 190 | # Crashlytics plugin (for Android Studio and IntelliJ) 191 | com_crashlytics_export_strings.xml 192 | crashlytics.properties 193 | crashlytics-build.properties 194 | fabric.properties 195 | 196 | # Editor-based Rest Client 197 | .idea/httpRequests 198 | 199 | # Android studio 3.1+ serialized cache file 200 | .idea/caches/build_file_checksums.ser 201 | 202 | ### Intellij+all Patch ### 203 | # Ignore everything but code style settings and run configurations 204 | # that are supposed to be shared within teams. 205 | 206 | .idea/* 207 | 208 | !.idea/codeStyles 209 | !.idea/runConfigurations 210 | 211 | ### Jekyll ### 212 | _site/ 213 | .sass-cache/ 214 | .jekyll-cache/ 215 | .jekyll-metadata 216 | # Ignore folders generated by Bundler 217 | .bundle/ 218 | vendor/ 219 | 220 | ### Linux ### 221 | 222 | # temporary files which can be created if a process still has a handle open of a deleted file 223 | .fuse_hidden* 224 | 225 | # KDE directory preferences 226 | .directory 227 | 228 | # Linux trash folder which might appear on any partition or disk 229 | .Trash-* 230 | 231 | # .nfs files are created when an open file is removed but is still being accessed 232 | .nfs* 233 | 234 | ### macOS ### 235 | # General 236 | .DS_Store 237 | .AppleDouble 238 | .LSOverride 239 | 240 | # Icon must end with two \r 241 | Icon 242 | 243 | 244 | # Thumbnails 245 | ._* 246 | 247 | # Files that might appear in the root of a volume 248 | .DocumentRevisions-V100 249 | .fseventsd 250 | .Spotlight-V100 251 | .TemporaryItems 252 | .Trashes 253 | .VolumeIcon.icns 254 | .com.apple.timemachine.donotpresent 255 | 256 | # Directories potentially created on remote AFP share 257 | .AppleDB 258 | .AppleDesktop 259 | Network Trash Folder 260 | Temporary Items 261 | .apdisk 262 | 263 | ### macOS Patch ### 264 | # iCloud generated files 265 | *.icloud 266 | 267 | ### Vim ### 268 | # Swap 269 | [._]*.s[a-v][a-z] 270 | !*.svg # comment out if you don't need vector files 271 | [._]*.sw[a-p] 272 | [._]s[a-rt-v][a-z] 273 | [._]ss[a-gi-z] 274 | [._]sw[a-p] 275 | 276 | # Session 277 | Session.vim 278 | Sessionx.vim 279 | 280 | # Temporary 281 | .netrwhist 282 | # Auto-generated tag files 283 | tags 284 | # Persistent undo 285 | [._]*.un~ 286 | 287 | ### Windows ### 288 | # Windows thumbnail cache files 289 | Thumbs.db 290 | Thumbs.db:encryptable 291 | ehthumbs.db 292 | ehthumbs_vista.db 293 | 294 | # Dump file 295 | *.stackdump 296 | 297 | # Folder config file 298 | [Dd]esktop.ini 299 | 300 | # Recycle Bin used on file shares 301 | $RECYCLE.BIN/ 302 | 303 | # Windows Installer files 304 | *.cab 305 | *.msi 306 | *.msix 307 | *.msm 308 | *.msp 309 | 310 | # Windows shortcuts 311 | *.lnk 312 | 313 | # End of https://www.toptal.com/developers/gitignore/api/vim,macos,linux,emacs,eclipse,windows,intellij+all,jekyll 314 | -------------------------------------------------------------------------------- /.gitpod.yml: -------------------------------------------------------------------------------- 1 | vscode: 2 | extensions: 3 | - DavidAnson.vscode-markdownlint 4 | - valentjn.vscode-ltex 5 | -------------------------------------------------------------------------------- /.lycheeignore: -------------------------------------------------------------------------------- 1 | 0005-example\.md 2 | https://medium\.com/.* 3 | -------------------------------------------------------------------------------- /.makrdownlint-cli2.yml: -------------------------------------------------------------------------------- 1 | customRules: 2 | - markdownlint-rule-github-internal-links 3 | - markdownlint-rule-list-duplicates 4 | - markdownlint-rule-titlecase 5 | -------------------------------------------------------------------------------- /.markdownlint.yml: -------------------------------------------------------------------------------- 1 | default: true 2 | 3 | # Allow arbitrary line length 4 | # 5 | # Reason: We apply the one-sentence-per-line rule. A sentence may get longer than 80 characters, especially if links are contained. 6 | # 7 | # Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length 8 | MD013: false 9 | 10 | # Allow duplicate headings 11 | # 12 | # Reasons: 13 | # 14 | # - The chosen option is considerably often used as title of the ADR (e.g., ADR-0015). Thus, that title repeats. 15 | # - We use "Examples" multiple times (e.g., ADR-0010). 16 | # - Markdown lint should support the user and not annoy them. 17 | # 18 | # Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content 19 | MD024: false 20 | -------------------------------------------------------------------------------- /.release-it.json: -------------------------------------------------------------------------------- 1 | {"requireCleanWorkingDir": false} 2 | -------------------------------------------------------------------------------- /.vscode/extensions.json: -------------------------------------------------------------------------------- 1 | { 2 | "recommendations": [ 3 | "davidanson.vscode-markdownlint", 4 | "ltex-plus.vscode-ltex-plus", 5 | ] 6 | } 7 | -------------------------------------------------------------------------------- /.vscode/ltex.dictionary.en-US.txt: -------------------------------------------------------------------------------- 1 | ADRs 2 | MADR 3 | MADRs 4 | Nygard 5 | RACI 6 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. 4 | 5 | The format is based on [Keep a Changelog](https://keepachangelog.com/) 6 | and this project adheres to [Semantic Versioning](https://semver.org/). 7 | 8 | ## [unreleased] 9 | 10 | ### Changed 11 | 12 | - Changed wording in "Confirmation" section. [#162](https://github.com/adr/madr/pull/162) 13 | 14 | ## [4.0.0] – 2024-09-17 15 | 16 | ### Fixed 17 | 18 | - `adr-template.md`: Re-add quotes around chosen option name. 19 | - `adr-template-minimal.md`: Place holder in one line. 20 | - `adr-template-bare.md`: Keep fixed template text as normal markdown (and not as comment). 21 | - `adr-template-bare.md` and `adr-template-bare-minimal.md`: Always use ` 29 | - [`adr-template-bare.md`](template/adr-template-bare.md) has all sections, wich are empty (no explanations). 30 | - [`adr-template-bare-minimal.md`](template/adr-template-bare-minimal.md) has the mandatory sections, without explanations. 31 | - Added example for "Confirmation". [#135](https://github.com/adr/madr/issues/135) 32 | 33 | ### Changed 34 | 35 | - Put the content of `status:` in quotes to tell YAML it's a string. [#91](https://github.com/adr/madr/issues/91) 36 | - Renamed "Validation" to "Confirmation" and put it as sub element of "Decision Outcome". [#87](https://github.com/adr/madr/pull/87) 37 | - Renamed "Deciders" to "Decision Maker(s)" (`decision-makers:`). [#101](https://github.com/adr/madr/issues/101) 38 | - Rename template name "Markdown Any Decision Record" back to "Markdown Architectural Decision Record" 39 | - Rename `0000-use-markdown-any-decision-records.md` to `0000-use-madr.md`. 40 | - All placehodlers are are now one liners. 41 | 42 | ### Removed 43 | 44 | - Removed link to ADR in `status` field. Only identifier should be put. [#150](https://github.com/adr/madr/pull/150) 45 | 46 | ## [3.0.0] – 2022-10-09 47 | 48 | ### Added 49 | 50 | - Added comments to [markdownlint rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#rules) in `.markdownlint.yml` files. 51 | 52 | ### Changed 53 | 54 | - Moved section "Validation" directly after "Decision Outcome" 55 | - Merged sections "Positive Consequences" and "Negative Consequences" into "Consequences" to enable similar grammar as in "Pros and Cons of the Options". [#75](https://github.com/adr/madr/issues/75) 56 | 57 | ### Removed 58 | 59 | - Removed allowed punctuation in `.markdownlint.yml` rule 60 | 61 | ## [3.0.0-beta.2] – 2022-05-25 62 | 63 | ### Added 64 | 65 | - Added front matter fields "consulted" and "informed" (inspired by [RACI](https://en.wikipedia.org/wiki/Responsibility_assignment_matrix#Role_distinction)). [#62](https://github.com/adr/madr/issues/62) 66 | - Added section "Validation" 67 | 68 | ### Changed 69 | 70 | - Moved markings for optional content from next to the heading above the heading 71 | 72 | ## [3.0.0-beta] – 2022-05-17 73 | 74 | ### Added 75 | 76 | - Added YAML front matter to `docs/decisions/adr-template.md` 77 | - Added "Neutral" arguments (in addition to "Good, because", and "Bad, because") 78 | - Refined howto texts 79 | - Disable [markdown-lint](https://github.com/DavidAnson/markdownlint)'s [MD013 - line length](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md013---line-length) for the ADR files. 80 | - Added initial [markdownlint](https://github.com/DavidAnson/markdownlint) configuration file `.markdownlint`. 81 | This can, for instance, be used by a [GitHub linting workflow](https://github.com/adr/madr/blob/develop/.github/workflows/lint.yaml) 82 | 83 | ### Changed 84 | 85 | - Rename "Markdown Architectural Decision Record" to "Markdown Any Decision Record" 86 | - Place holders for values are denoted by curly braces (`{placehodler}`). Before it was `[placeholder]`. [#35](https://github.com/adr/madr/issues/35) 87 | - Directory of ADRs changed from `docs/adr` to `docs/decisions`. [#33](https://github.com/adr/madr/issues/33) 88 | - Renamed `template.md` to `adr-template.md`. [#36](https://github.com/adr/madr/issues/36) 89 | - Changed `## Links` to `## More information` 90 | - Relaxed content of `More information` section from a bullet list to free text. 91 | - Changed `optional` to `This is an optional element. Feel free to remove.` to make it more clear how to work with an optional element. 92 | - Changed `driver 1` to `decision driver 1`. 93 | - Changed `e.g., compromising quality attribute, follow-up decisions required, …` to `e.g., compromising one or more desired qualities, …` 94 | - Moved the fields to the YAML front matter 95 | - Renamed `template/index.md` to `template/README.md`, because i) `README.md` is directly rendered on GitHub and ii) for Jekyll-based rendering, the index file has to be adapted (e.g., to show a hint to the doc as MADR does in `docs/decisions/index.md`). 96 | - Replace `{option 1}` place holder to `{title of option 1}`. 97 | - Restructured and streamlined documentation. 98 | 99 | ### Removed 100 | 101 | - Removed `Technical Story: {description | ticket/issue URL} `, because all description should go into "Context and Problem Statement" 102 | - Removed files `.adr-dir` and `.adr-type` as tooling should automatically detect the style of the template 103 | 104 | ## [2.1.2] – 2019-02-17 105 | 106 | ### Added 107 | 108 | - Add more status fields. Source: [#20](https://github.com/adr/madr/pull/20). 109 | 110 | ### Fixed 111 | 112 | - Fixed typos in `README.md`. 113 | 114 | ## [2.1.1] – 2019-01-21 115 | 116 | ### Fixed 117 | 118 | - Fix typo in heading. Fixes [#18](https://github.com/adr/madr/issues/18) 119 | 120 | ## [2.1.0] – 2018-06-14 121 | 122 | ### Changed 123 | 124 | - Headings "Positive/negative consequences" now full h3 headings instead of text headings 125 | - Adapted internal ADRs to new format 126 | 127 | ### Added 128 | 129 | - Added ADR-0011 stating that we use an asterisk as list marker 130 | 131 | ## [2.0.3] – 2018-03-21 132 | 133 | ### Fixed 134 | 135 | - Fix reference to MADR version in ADR-0000 and README.md 136 | 137 | ## [2.0.2] – 2018-03-16 138 | 139 | ### Changed 140 | 141 | - Streamlined template's ADR-0000. 142 | - Streamlined template by using ellipsis and removing double empty lines. 143 | 144 | ## [2.0.1] – 2018-03-07 145 | 146 | ### Fixed 147 | 148 | - State MADR 2.0.1 also in template's ADR-0000. 149 | 150 | ## [2.0.0] – 2018-03-07 151 | 152 | ### Added 153 | 154 | - Optional: Status, Deciders, Date. Fixes [#2](https://github.com/adr/madr/issues/2). 155 | - More explanations of options can now be put next to each option 156 | - Links to other ADRs added at the bottom of the ADR 157 | 158 | ### Changed 159 | 160 | - Rename "User Story" to "Technical Story" 161 | - "Context and Problem Statement" and "Decision Drivers" are a heading now 162 | - The chosen option is now written in quotes to separate the name from the rest of the text 163 | - All bullet lists are now made using `*` (instead of `-` at some lists) 164 | 165 | ## [1.4.0] – 2018-03-01 166 | 167 | ### Added 168 | 169 | - Version of MADR into `ADR-0000` of the template. Fixes [#5](https://github.com/adr/madr/issues/5) 170 | - `README.md`: Added wints on the filenames. 171 | - More ADRs on MADR 172 | - Added `LICENSE` file 173 | 174 | ### Changed 175 | 176 | - `README.md`: Removed section "Background Information" as the information is contained at , too. Fixes [#4](https://github.com/adr/madr/issues/4) 177 | 178 | ## [1.3.1] – 2018-02-13 179 | 180 | ### Fixed 181 | 182 | - Replace "alternative" by "option" in all `md` files 183 | - Update to new "Decision Outcome" format in all `md` files 184 | 185 | ## [1.3.0] – 2018-01-30 186 | 187 | ### Changed 188 | 189 | - Changed template to be closer to the [Y-Statements](https://www.infoq.com/articles/sustainable-architectural-design-decisions). 190 | Especially rename "alternative" to "option". 191 | - Restructured syntax of "Decision Outcome". 192 | Positive and negative consequences as separate bullet list. 193 | - Rename "point" to "argument" (which reverts the change of version 1.2.0) 194 | - Number "arguments" from a to c. Re-use "variables" a to c to guide the author that the same topic should be handled by the enumeration. e..g, performance, ... 195 | - Exchange `+` and `-` by "Good, because ..." and "Bad, because ..." 196 | - Remove emphasize of "User Story:" 197 | 198 | ## [1.2.0] – 2018-01-26 199 | 200 | ### Added 201 | 202 | - Add installation instructions using `npm`. 203 | 204 | ### Changed 205 | 206 | - Placeholders changed from `*[PLACEHOLDER]*` to `[PLACEHOLDER]` to have a single pair of enclosing characters (`[]`) instead of two (`*[]*`). 207 | - Rename `argument 1 pro` to `pro point` and `argument 1 con` to `con point` 208 | 209 | ## [1.1.1] – 2017-12-05 210 | 211 | ### Changed 212 | 213 | - Simplify `package.json` and fix name. 214 | 215 | ## [1.1.0] – 2017-12-04 216 | 217 | ### Changed 218 | 219 | - No change in the template itself. 220 | - Use [adr-log](https://github.com/adr/adr-log?tab=readme-ov-file#adr-log-) to generate links to the ADRs in `docs/adr/index.md`. 221 | - `template.md` is not part of the log, but a separate text block in `docs/adr/index.md`. 222 | - Link to new homepage of MADR: . 223 | - Refined justification of `ADR-0000`. 224 | - Refined `README.md`. 225 | 226 | ### Fixed 227 | 228 | - Fixed internal links in `docs/adr/index.md`. 229 | - Fixed typo in `docs/adr/0000-use-markdown-architectural-decision-records.md`. 230 | 231 | ## [1.0.0] – 2017-09-09 232 | 233 | First release of Markdown Architectural Decision Records. 234 | 235 | [unreleased]: https://github.com/adr/madr/compare/4.0.0...develop 236 | [4.0.0]: https://github.com/adr/madr/compare/4.0.0-beta...4.0.0 237 | [4.0.0-beta]: https://github.com/adr/madr/compare/3.0.0...4.0.0-beta 238 | [3.0.0]: https://github.com/adr/madr/compare/3.0.0-beta.2...3.0.0 239 | [3.0.0-beta.2]: https://github.com/adr/madr/compare/3.0.0-beta...3.0.0-beta.2 240 | [3.0.0-beta]: https://github.com/adr/madr/compare/2.1.2...3.0.0-beta 241 | [2.1.2]: https://github.com/adr/madr/compare/2.1.1...2.1.2 242 | [2.1.1]: https://github.com/adr/madr/compare/2.1.0...2.1.1 243 | [2.1.0]: https://github.com/adr/madr/compare/2.0.3...2.1.0 244 | [2.0.3]: https://github.com/adr/madr/compare/2.0.2...2.0.3 245 | [2.0.2]: https://github.com/adr/madr/compare/2.0.1...2.0.2 246 | [2.0.1]: https://github.com/adr/madr/compare/2.0.0...2.0.1 247 | [2.0.0]: https://github.com/adr/madr/compare/1.4.0...2.0.0 248 | [1.4.0]: https://github.com/adr/madr/compare/1.3.1...1.4.0 249 | [1.3.1]: https://github.com/adr/madr/compare/1.3.0...1.3.1 250 | [1.3.0]: https://github.com/adr/madr/compare/1.2.0...1.3.0 251 | [1.2.0]: https://github.com/adr/madr/compare/1.1.1...1.2.0 252 | [1.1.1]: https://github.com/adr/madr/compare/1.1.0...1.1.1 253 | [1.1.0]: https://github.com/adr/madr/compare/1.0.0...1.1.0 254 | [1.0.0]: https://github.com/adr/madr/releases/tag/1.0.0 255 | 256 | 257 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to MADR 2 | 3 | ## Homepage 4 | 5 | Homepage: Contribute to `gh-pages` branch (using a pull request). 6 | The `docs/` folder of the `gh-pages` branch is the base of the content of . 7 | 8 | ## Template: Next version 9 | 10 | Template: Contribute to `develop` branch (using a pull request). 11 | The subdirectory `docs/` will be the new homepage after a release. 12 | The current state is rendered at . 13 | 14 | As soon as a pull request is made, [netlify](https://www.netlify.com/) kicks off a build. 15 | After a successful build, the link to the build is put as a comment to the pull request for inspection. 16 | 17 | We use `develop` as branch name, because the name `main` does not definitively indicate whether it is the latest releae or the development version. 18 | 19 | ## Template: Patches to releases 20 | 21 | The most recent releases of each major version are stored in the branch `release/v{x}`. 22 | It is a branch, because the release version changes (and there are git users who do not like changing tags). 23 | 24 | Please submit a pull request to that branch. 25 | In case there are multiple fixes, we create a new branch `develop/v{x}` on demand. 26 | 27 | Reasing: Wish at [#92](https://github.com/adr/madr/issues/92) 28 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT OR CC0-1.0 2 | -------------------------------------------------------------------------------- /LICENSE.CC0-1.0: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | -------------------------------------------------------------------------------- /LICENSE.MIT: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017-2022 Oliver Kopp, Olaf Zimmermann 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Markdown Architectural Decision Records 2 | 3 | > "Markdown Architectural Decision Records" (MADR) `[ˈmæɾɚ]` – decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). 4 | 5 | For user documentation, please head to . 6 | 7 | ## Quick start 8 | 9 | * [`adr-template.md`](template/adr-template.md) has all sections, with explanations about them. 10 | * [`adr-template-minimal.md`](template/adr-template-minimal.md) only contains mandatory sections, with explanations about them. 11 | * [`adr-template-bare.md`](template/adr-template-bare.md) has all sections, which are empty (no explanations). 12 | * [`adr-template-bare-minimal.md`](template/adr-template-bare-minimal.md) has the mandatory sections, without explanations. 13 | 14 | Copy it into `docs/decisions`. 15 | For each ADR, copy the template to `nnnn-title.md` and adapt. 16 | Longer explanation: Head to . 17 | 18 | ## Development hints 19 | 20 | * 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/). 21 | * Issues can be reported at . 22 | * 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). 23 | * 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. 24 | * `template/adr-template.md` is mirrored to `docs/decisions/adr-template`. 25 | 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/). 26 | ```markdown 27 | --- 28 | parent: Decisions 29 | nav_order: 100 30 | title: ADR Template 31 | --- 32 | ``` 33 | 34 | ### Branches 35 | 36 | | Branch | Meaning | 37 | |--------------|----------------------------------------------------------------------------------------------------------------------------------------------| 38 | | `gh-pages` | Homepage showing the latest released version, rendered at | 39 | | `develop` | Latest developments, including homepage updates which should be published on a release. `gh-pages` should always be merged into this branch. | 40 | | `release/vY` | Branch for latest release Y.x version of MADR. Introduced to fix [#92](https://github.com/adr/madr/issues/92) | 41 | 42 | The branch name conventions follow the [git flow model](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). 43 | 44 | See also [`CONTRIBUTING.md`](CONTRIBUTING.md). 45 | 46 | ## How to start Jekyll locally 47 | 48 | For rendering the `docs` directory, Jekyll is needed. 49 | 50 | For local development, follow the [Jekyll installation instructions](https://jekyllrb.com/docs/installation/). 51 | Installing the latest version of ruby followed by `gem install bundler` should be enough. 52 | 53 | Afterwards, run 54 | 55 | ```terminal 56 | bundle install 57 | jekyll serve --livereload 58 | ``` 59 | 60 | and go to in your browser. 61 | 62 | On Windows, using a dockerized environment is recommended: 63 | 64 | ```terminal 65 | docker run -p 4000:4000 --rm -v "C:\git-repositories\adr.github.io\madr\docs":/site bretfisher/jekyll-serve 66 | ``` 67 | 68 | In case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and rerun. 69 | 70 | ## Updating just-the-docs 71 | 72 | * Adapt `docs/Gemfile` to use newer just-the-docs version. Thereby check for versions. 73 | * Delete `docs/Gemfile.lock`. Start `bundle install`. 74 | * Check . 75 | * Check . 76 | 77 | ## Releasing a new version 78 | 79 | 1. Update the examples at `docs/index.md` and `docs/examples.md`. 80 | 2. Update the concrete decisions in `docs/decisions/*` with the new template. 81 | 3. Commit ("Update examples and decisions") and push. Possibly as pull request. 82 | 4. Adapt the version reference in `template/0000-use-markdown-architectural-decision-records.md`. 83 | 5. Update "template" files in `docs/decisions`: 84 | * Copy `template/0000-use-markdown-architectural-decision-records.md` to `docs/decisions/0000-use-markdown-architectural-decision-records.md`. 85 | * Adapt content of `docs/decisions/adr-template.md` based on `template/adr-template.md`. 86 | Thereby, ensure that the YAML front matter in `docs/decisions/adr-template.md` is kept. 87 | 6. Add link to `docs/index.md` at "Older versions" (for the homepage). 88 | 7. Copy `.markdownlint.yml` to `template/.markdownlint.yml` (and possibly to `docs/.markdownlint.yml`). 89 | 8. Update `CHANGELOG.md`. 90 | 9. Commit. 91 | 10. 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. 92 | 11. Create GitHub release using [github-release-from-changelog](https://www.npmjs.com/package/github-release-from-changelog). 93 | 12. Merge `develop` into `gh-pages` 94 | 95 | ## License 96 | 97 | This work is dual-licensed under [MIT](https://opensource.org/licenses/MIT) and 98 | [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/). 99 | You can choose between one of them if you use this work. 100 | 101 | ```yaml 102 | SPDX-License-Identifier: MIT OR CC0-1.0 103 | ``` 104 | -------------------------------------------------------------------------------- /docs/.ruby-version: -------------------------------------------------------------------------------- 1 | 3.1.6 2 | -------------------------------------------------------------------------------- /docs/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM ruby:2.7 2 | 3 | ENV LC_ALL C.UTF-8 4 | ENV LANG en_US.UTF-8 5 | ENV LANGUAGE en_US.UTF-8 6 | 7 | EXPOSE 4000 8 | 9 | WORKDIR /srv/jekyll 10 | COPY . /srv/jekyll 11 | 12 | RUN gem install bundler && bundle install 13 | 14 | CMD bundle exec jekyll serve -H 0.0.0.0 -t 15 | -------------------------------------------------------------------------------- /docs/Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | 3 | gem "jekyll", "~> 4.3.3" 4 | 5 | gem "just-the-docs", "0.8.2" 6 | 7 | gem 'jekyll-titles-from-headings' 8 | 9 | gem 'jekyll-relative-links' 10 | -------------------------------------------------------------------------------- /docs/Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | addressable (2.8.7) 5 | public_suffix (>= 2.0.2, < 7.0) 6 | bigdecimal (3.1.8) 7 | colorator (1.1.0) 8 | concurrent-ruby (1.3.4) 9 | em-websocket (0.5.3) 10 | eventmachine (>= 0.12.9) 11 | http_parser.rb (~> 0) 12 | eventmachine (1.2.7) 13 | ffi (1.17.0) 14 | ffi (1.17.0-arm64-darwin) 15 | ffi (1.17.0-x86_64-darwin) 16 | ffi (1.17.0-x86_64-linux-gnu) 17 | forwardable-extended (2.6.0) 18 | google-protobuf (4.28.2) 19 | bigdecimal 20 | rake (>= 13) 21 | google-protobuf (4.28.2-arm64-darwin) 22 | bigdecimal 23 | rake (>= 13) 24 | google-protobuf (4.28.2-x86_64-darwin) 25 | bigdecimal 26 | rake (>= 13) 27 | google-protobuf (4.28.2-x86_64-linux) 28 | bigdecimal 29 | rake (>= 13) 30 | http_parser.rb (0.8.0) 31 | i18n (1.14.5) 32 | concurrent-ruby (~> 1.0) 33 | jekyll (4.3.3) 34 | addressable (~> 2.4) 35 | colorator (~> 1.0) 36 | em-websocket (~> 0.5) 37 | i18n (~> 1.0) 38 | jekyll-sass-converter (>= 2.0, < 4.0) 39 | jekyll-watch (~> 2.0) 40 | kramdown (~> 2.3, >= 2.3.1) 41 | kramdown-parser-gfm (~> 1.0) 42 | liquid (~> 4.0) 43 | mercenary (>= 0.3.6, < 0.5) 44 | pathutil (~> 0.9) 45 | rouge (>= 3.0, < 5.0) 46 | safe_yaml (~> 1.0) 47 | terminal-table (>= 1.8, < 4.0) 48 | webrick (~> 1.7) 49 | jekyll-include-cache (0.2.1) 50 | jekyll (>= 3.7, < 5.0) 51 | jekyll-relative-links (0.7.0) 52 | jekyll (>= 3.3, < 5.0) 53 | jekyll-sass-converter (3.0.0) 54 | sass-embedded (~> 1.54) 55 | jekyll-seo-tag (2.8.0) 56 | jekyll (>= 3.8, < 5.0) 57 | jekyll-titles-from-headings (0.5.3) 58 | jekyll (>= 3.3, < 5.0) 59 | jekyll-watch (2.2.1) 60 | listen (~> 3.0) 61 | just-the-docs (0.8.2) 62 | jekyll (>= 3.8.5) 63 | jekyll-include-cache 64 | jekyll-seo-tag (>= 2.0) 65 | rake (>= 12.3.1) 66 | kramdown (2.4.0) 67 | rexml 68 | kramdown-parser-gfm (1.1.0) 69 | kramdown (~> 2.0) 70 | liquid (4.0.4) 71 | listen (3.9.0) 72 | rb-fsevent (~> 0.10, >= 0.10.3) 73 | rb-inotify (~> 0.9, >= 0.9.10) 74 | mercenary (0.4.0) 75 | pathutil (0.16.2) 76 | forwardable-extended (~> 2.6) 77 | public_suffix (6.0.1) 78 | rake (13.2.1) 79 | rb-fsevent (0.11.2) 80 | rb-inotify (0.11.1) 81 | ffi (~> 1.0) 82 | rexml (3.3.9) 83 | rouge (4.3.0) 84 | safe_yaml (1.0.5) 85 | sass-embedded (1.77.8) 86 | google-protobuf (~> 4.26) 87 | rake (>= 13) 88 | sass-embedded (1.77.8-aarch64-mingw-ucrt) 89 | google-protobuf (~> 4.26) 90 | sass-embedded (1.77.8-arm64-darwin) 91 | google-protobuf (~> 4.26) 92 | sass-embedded (1.77.8-x86-cygwin) 93 | google-protobuf (~> 4.26) 94 | sass-embedded (1.77.8-x86-mingw-ucrt) 95 | google-protobuf (~> 4.26) 96 | sass-embedded (1.77.8-x86_64-cygwin) 97 | google-protobuf (~> 4.26) 98 | sass-embedded (1.77.8-x86_64-darwin) 99 | google-protobuf (~> 4.26) 100 | terminal-table (3.0.2) 101 | unicode-display_width (>= 1.1.1, < 3) 102 | unicode-display_width (2.5.0) 103 | webrick (1.8.2) 104 | 105 | PLATFORMS 106 | aarch64-mingw-ucrt 107 | arm64-darwin 108 | ruby 109 | x86-cygwin 110 | x86-mingw-ucrt 111 | x86_64-cygwin 112 | x86_64-darwin 113 | x86_64-linux 114 | 115 | DEPENDENCIES 116 | jekyll (~> 4.3.3) 117 | jekyll-relative-links 118 | jekyll-titles-from-headings 119 | just-the-docs (= 0.8.2) 120 | 121 | BUNDLED WITH 122 | 2.5.10 123 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # Web Page of MADR 2 | 3 | The web site is created using the Jekyll Theme [Just the Docs](https://just-the-docs.github.io/just-the-docs/). 4 | 5 | ## Local Development 6 | 7 | For local development, follow the [Jekyll installation instructions](https://jekyllrb.com/docs/installation/). 8 | Installing the latest version of ruby followed by `gem install bundler` should be enough. 9 | 10 | Afterwards, run 11 | 12 | ```terminal 13 | bundle install 14 | jekyll serve --livereload 15 | ``` 16 | 17 | and go to in your browser. 18 | 19 | On **Windows**, using a dockerized environment is recommended: 20 | 21 | ```terminal 22 | docker build . -t madrjekyll 23 | docker run -p 4000:4000 -it --rm --volume="C:\git-repositories\madr\docs":/srv/jekyll madrjekyll jekyll serve -H 0.0.0.0 -t 24 | ``` 25 | 26 | * With Ctrl+C you can stop the server (this is enabled by the `-it` switch). 27 | * In case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and rerun. 28 | * The current `Dockerfile` is based on . 29 | The [Jekyll Docker image](https://github.com/envygeeks/jekyll-docker#jekyll-docker) did not work end of 20222 (because Ruby was too new). 30 | 31 | 32 | -------------------------------------------------------------------------------- /docs/_config.yml: -------------------------------------------------------------------------------- 1 | title: "MADR" 2 | desription: Markdown Architectural Decisions Records 3 | repository: adr/madr 4 | theme: just-the-docs 5 | color_scheme: adr 6 | 7 | defaults: 8 | - 9 | scope: 10 | path: "**/*.md" 11 | values: 12 | layout: "page" 13 | 14 | exclude: [Dockerfile, README.md, Gemfile, Gemfile.lock] 15 | 16 | # Hint by https://github.com/just-the-docs/just-the-docs/issues/374#issuecomment-680273258 17 | # Theme read from https://github.com/StylishThemes/Syntax-Themes/blob/master/pygments/css-github/ 18 | # Browse alternative themes at https://stylishthemes.github.io/Syntax-Themes/pygments/ 19 | highlight_theme: jellybeans 20 | 21 | search_enabled: true 22 | button: true 23 | aux_links: 24 | "ADR GitHub Organization": 25 | - "https://adr.github.io/" 26 | "Code Repository": 27 | - "https://github.com/adr/madr/" 28 | aux_links_new_tab: false 29 | last_edit_timestamp: false # show or hide edit time - page must have `last_modified_date` defined in the frontmatter 30 | last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html 31 | gh_edit_link: true 32 | gh_edit_link_text: "Edit this page on GitHub." 33 | gh_edit_repository: "https://github.com/adr/madr/" 34 | gh_edit_branch: "gh-pages" 35 | gh_edit_source: "docs" 36 | gh_edit_view_mode: "edit" 37 | 38 | # ga_tracking: UA-5555555-55 39 | # ga_tracking_anonymize_ip: true 40 | 41 | baseurl: "" 42 | url: "https://adr.github.io" 43 | 44 | plugins: 45 | - jekyll-titles-from-headings 46 | - jekyll-relative-links 47 | -------------------------------------------------------------------------------- /docs/_sass/color_schemes/adr.scss: -------------------------------------------------------------------------------- 1 | @import "./color_schemes/dark"; 2 | 3 | $body-background-color: #1f1f1f; 4 | $body-heading-color: lighten($body-text-color, 1%); 5 | $body-text-color: #cccccc; 6 | $link-color: #488ad1; 7 | $nav-child-link-color: $grey-dk-000; 8 | $sidebar-color: #1f1f1f; 9 | $base-button-color: $grey-dk-250; 10 | $btn-primary-color: $blue-200; 11 | $code-background-color: #1f1f1f; 12 | $code-linenumber-color: #cccccc; 13 | $feedback-color: darken($sidebar-color, 3%); 14 | $table-background-color: lighten($body-background-color, 1%); 15 | $search-background-color: lighten($body-background-color, 3%); 16 | $search-result-preview-color: $grey-dk-000; 17 | 18 | // cannot disable border, due to higher priority of code.scss 19 | $border-color: #1f1f1f; 20 | -------------------------------------------------------------------------------- /docs/decisions/.markdownlint.yml: -------------------------------------------------------------------------------- 1 | default: true 2 | 3 | # Allow arbitrary line length 4 | # 5 | # Reason: We apply the one-sentence-per-line rule. A sentence may get longer than 80 characters, especially if links are contained. 6 | # 7 | # Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length 8 | MD013: false 9 | 10 | # Allow duplicate headings 11 | # 12 | # Reasons: 13 | # 14 | # - The chosen option is considerably often used as title of the ADR (e.g., ADR-0015). Thus, that title repeats. 15 | # - We use "Examples" multiple times (e.g., ADR-0010). 16 | # - Markdown lint should support the user and not annoy them. 17 | # 18 | # Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content 19 | MD024: false 20 | -------------------------------------------------------------------------------- /docs/decisions/0000-use-markdown-architectural-decision-records.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 0 4 | --- 5 | # Use Markdown Architectural Decision Records 6 | 7 | ## Context and Problem Statement 8 | 9 | We want to record architectural decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields. 10 | Which format and structure should these records follow? 11 | 12 | ## Considered Options 13 | 14 | * [MADR](https://adr.github.io/madr/) 4.0.0 – The Markdown Architectural Decision Records 15 | * [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR" 16 | * [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements 17 | * Other templates listed at 18 | * Formless – No conventions for file format and structure 19 | 20 | ## Decision Outcome 21 | 22 | Chosen option: "MADR 4.0.0", because 23 | 24 | * Implicit assumptions should be made explicit. 25 | Design documentation is important to enable people understanding the decisions later on. 26 | See also ["A rational design process: How and why to fake it"](https://doi.org/10.1109/TSE.1986.6312940). 27 | * MADR allows for structured capturing of any decision. 28 | * The MADR format is lean and fits our development style. 29 | * The MADR structure is comprehensible and facilitates usage & maintenance. 30 | * The MADR project is vivid. 31 | -------------------------------------------------------------------------------- /docs/decisions/0001-use-CC0-or-MIT-as-license.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 1 4 | --- 5 | # Dual License the Work 6 | 7 | ## Context and Problem Statement 8 | 9 | Everything needs to be licensed, otherwise the default copyright laws apply. 10 | For instance, in Germany that means users may not alter anything without explicitly asking for permission. 11 | For more information see . 12 | 13 | We want to have MADR used without any hassle and that users can just go ahead and write MADRs. 14 | 15 | ## Considered Options 16 | 17 | * [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/) 18 | * BSD3 19 | * MIT 20 | * Dual license with MIT and CC0 21 | * No license 22 | * Other open source licenses 23 | 24 | ## Decision Outcome 25 | 26 | Chosen option: "Dual license with MIT and CC0", because this lets users choose whether CC0 or MIT fits better on their work. 27 | 28 | ## Pros and Cons of the Options 29 | 30 | ### CC0 31 | 32 | * Good, because this license donates the content to "public domain" and does so as legally as possible. 33 | * Bad, because it does not contain attribution - and [attribution is important](https://opensource.stackexchange.com/a/9126/5671). 34 | 35 | ### BSD3 36 | 37 | * Bad, because it [is unclear whether it can be used for documentation](https://opensource.stackexchange.com/a/9545/5671) 38 | 39 | ### MIT 40 | 41 | * Good, because it [explicitly may be used for documentation](https://opensource.stackexchange.com/a/9545/5671) 42 | * Good, because it is lean. 43 | 44 | ### Dual license with MIT and CC0 45 | 46 | With the SPDX identifier `MIT OR CC0-1.0`, the receiver of the documents can decide which license thay want to use. 47 | 48 | * Good, because offers freedom at the receiver 49 | * Bad, because dual licensing is not widely known 50 | -------------------------------------------------------------------------------- /docs/decisions/0002-do-not-use-numbers-in-headings.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 2 4 | --- 5 | # Do Not Use Numbers in Headings 6 | 7 | ## Context and Problem Statement 8 | 9 | How to render the first line in an ADR? 10 | ADRs have to take a unique identifier. 11 | 12 | ## Considered Options 13 | 14 | * Use the title only 15 | * Add the ADR number in front of the title (e.g., "# 2. Do not use numbers in headings") 16 | 17 | ## Decision Outcome 18 | 19 | Chosen option: "Use the title only", because 20 | 21 | * This is common in other markdown files, too. 22 | One does not add numbering manually at the markdown files, but tries to get the numbers injected by the rendering framework or CSS. 23 | * Enables renaming of ADRs (before publication) easily 24 | * Allows copy'n'paste of ADRs from other repositories without having to worry about the numbers. 25 | -------------------------------------------------------------------------------- /docs/decisions/0003-provide-own-madr-tools.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 3 4 | status: on hold 5 | --- 6 | # Write Own MADR Tooling 7 | 8 | ## Context and Problem Statement 9 | 10 | Developers seem to like tooling to create ADRs. 11 | That tooling should support MADR. 12 | The tooling should be easy to install. 13 | 14 | ## Considered Options 15 | 16 | * Include in [adr-tools](https://github.com/npryce/adr-tools), 924 stars as of 2018-06-14 17 | * Include in [adr-j](https://github.com/adoble/adr-j), 2 stars as of 2018-06-14 18 | * Include in [adr](https://github.com/phodal/adr), 72 stars as of 2018-06-14 19 | * Write own MADR tooling 20 | * No tool support 21 | 22 | ## Decision Outcome 23 | 24 | Chosen option: "Write own MADR tooling", because 25 | 26 | * adding MADR support to `adr-tools` [was rejected](https://github.com/npryce/adr-tools/pull/43) 27 | * other tooling seem to a) modify MADR or b) do not keep up with changes on MADR. 28 | 29 | We accept that this comes with maintenance cost. 30 | 31 | ## More Information 32 | 33 | An overview on current tooling of MADR is available at . 34 | -------------------------------------------------------------------------------- /docs/decisions/0004-write-own-toc-tool.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 4 4 | --- 5 | # Write Own TOC Tool 6 | 7 | ## Context and Problem Statement 8 | 9 | ADRs have to be indexed somehow. E.g., for offering a website showing all ADRs. 10 | 11 | ## Considered Options 12 | 13 | * Write own tool `adr-log` 14 | * Use `adr-tools`' TOC functionality 15 | 16 | ## Decision Outcome 17 | 18 | Chosen option: "Write own tool `adr-log`", because 19 | 20 | * we want to have the format `ADR-0001 - Title` in the TOC. 21 | * `adr-tools` offers `title` only. 22 | 23 | We accept that changing `adr-tools` would also be possible. 24 | It is prepared to included header and footer: . 25 | 26 | ### Consequences 27 | 28 | * Good, because `adr-log` is installable using `npm install -g adr-log`, which is easier than installing `adr-tools`. 29 | * Bad, because another tool has to be maintained 30 | -------------------------------------------------------------------------------- /docs/decisions/0005-use-dashes-in-filenames.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 5 4 | --- 5 | # Use Dashes in Filenames 6 | 7 | ## Context and Problem Statement 8 | 9 | What is the pattern of the filename where an ADR is stored? 10 | 11 | ## Considered Options 12 | 13 | * `NNNN-title-with-dashes.md` - format used by [adr-tools](https://github.com/npryce/adr-tools) 14 | * `YYYY-MM-DD Title` - see 15 | 16 | ## Decision Outcome 17 | 18 | Chosen option: "`NNNN-title-with-dashes.md`", because 19 | 20 | * `NNNN` provides a unique number, which can be used for referencing in the forms 21 | * `ADR-0001` in plain text and 22 | * by `@ADR(1)` Java code (enabled by [e-adr](https://adr.github.io/e-adr/)) 23 | * The creation time of an ADR is of historical interest only, if it gets updated somehow. 24 | The arguments are similar than the ones by [Does Git have keyword expansion?](https://git.wiki.kernel.org/index.php/GitFaq#Does_Git_have_keyword_expansion.3F) 25 | * Having no spaces in filenames eases working in the command line 26 | * This is exactly the format offered by [adr-tools](https://github.com/npryce/adr-tools) 27 | -------------------------------------------------------------------------------- /docs/decisions/0006-use-names-as-identifier.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 6 4 | --- 5 | # Use Names as Identifier 6 | 7 | ## Context and Problem Statement 8 | 9 | An option is listed at "Considered Options" and repeated at "Pros and Cons of the Options". Finally, the chosen option is stated at "Decision Outcome". 10 | 11 | ## Decision Drivers 12 | 13 | * Easy to read 14 | * Easy to write 15 | * Avoid copy and paste errors 16 | 17 | ## Considered Options 18 | 19 | * Repeat all option names if they occur 20 | * Assign an identifier to an option, e.g., `[A] Use gradle as build tool` 21 | 22 | ## Decision Outcome 23 | 24 | Chosen option: "Repeat all option names if they occur", because 1) there is no markdown standard for identifiers, 2) the document is harder to read if there are multiple options which must be remembered. 25 | -------------------------------------------------------------------------------- /docs/decisions/0007-do-not-emphasize-line-headings.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 7 4 | --- 5 | # Do Not Emphasize Line Headings 6 | 7 | ## Context and Problem Statement 8 | 9 | MADR contains lines such as `Chosen option: "[option 1]"`. Should "Chosen option" be emphasized? 10 | 11 | ## Decision Drivers 12 | 13 | * MADR should be easy to read 14 | * MADR should be easy to write 15 | 16 | ## Considered Options 17 | 18 | * Do not emphasize line headings 19 | * Emphasize line headings 20 | 21 | ## Decision Outcome 22 | 23 | Chosen option: "Do not emphasize line headings", because 1) these headings always are put at the beginning of a line and followed by a colon. Thus, they are already easy to identified as line heading. 2) Readers not familiar with Markdown might be confused by stars in the text. 24 | -------------------------------------------------------------------------------- /docs/decisions/0008-add-status-field.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 8 4 | --- 5 | # Add Status Field 6 | 7 | ## Context and Problem Statement 8 | 9 | Technical Story: 10 | 11 | ADRs have a status. Should this be tracked? And if it should, how should we track it? 12 | 13 | ## Considered Options 14 | 15 | * Use YAML front matter 16 | * Use badge 17 | * Use text line 18 | * Use separate heading 19 | * Use table 20 | * Do not add status 21 | 22 | ## Decision Outcome 23 | 24 | Chosen option: "Use YAML front matter", because comes out best (see below). 25 | 26 | ## Pros and Cons of the Options 27 | 28 | ### Use YAML front matter 29 | 30 | Example: 31 | 32 | ```markdown 33 | --- 34 | parent: Decisions 35 | nav_order: 3 36 | status: on hold 37 | --- 38 | # Write own MADR tooling 39 | ``` 40 | 41 | * Good, because YAML front matter is supported by most Markdown parsers 42 | 43 | ### Use badge 44 | 45 | #### Examples 46 | 47 | * ![Example "Use Angular" with "status: accepted"](0008-example-badge.png) 48 | * [![Example "status: superseded"](https://img.shields.io/badge/status-superseeded_by_ADR_0001-orange.svg?style=flat-square)](https://github.com/adr/madr/blob/develop/docs/decisions/0001-use-CC0-or-MIT-as-license.md) 49 | 50 | --- 51 | 52 | * Good, because plain markdown 53 | * Good, because looks good 54 | * Bad, because hard to read in markdown source 55 | * Bad, because relies on the online service or [local badges have to be generated](https://github.com/badges/shields#using-the-badge-library) 56 | * Bad, because at local usages, many badges have to be generated (superseeded-by-ADR-0006, for each ADR number) 57 | * Bad, because not easy to write 58 | 59 | ### Use text line 60 | 61 | Example: `Status: Accepted` 62 | 63 | * Good, because plain markdown 64 | * Good, because easy to read 65 | * Good, because easy to write 66 | * Good, because looks OK in both markdown-source (MD) and in rendered versions (HTML, PDF) 67 | * Good, because no dependencies on external tools 68 | * Good, because single line indicates the current state 69 | * Bad, because "Status" line needs to be maintained 70 | * Bad, because uses space at the beginning. When users read MADR, they should directly dive into the context and problem and not into the status 71 | 72 | ### Use separate heading 73 | 74 | Example: ![example for separate heading](0008-example-separate-heading.png) 75 | 76 | * Good, because plain markdown 77 | * Good, because easy to write 78 | * Bad, because it uses much space: At least three lines: heading, status, separating empty line 79 | 80 | ### Use table 81 | 82 | Example: ![example for table](0008-example-table.png) 83 | 84 | * Good, because history can be included 85 | * Good, because multiple entries can be made 86 | * Good, because already implemented in `adr-tools` fork 87 | * Bad, because not covered by the [CommonMark specification 0.28 (2017-08-01)](http://spec.commonmark.org/0.28/) 88 | * Bad, because hard to read 89 | * Bad, because outdated entries cannot be easily identified 90 | * Bad, because needs more markdown training 91 | 92 | ### Do not add status 93 | 94 | * Good, because MADR is kept lean 95 | * Bad, because users demand state field 96 | * Bad, because not in line with other ADR templates 97 | 98 | ## More Information 99 | 100 | See [ADR-0013](0013-use-yaml-front-matter-for-meta-data.md) for more reasoning on using YAML front matter. 101 | -------------------------------------------------------------------------------- /docs/decisions/0008-example-badge.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adr/madr/be17f6683818534f34b4f4d433c718d46121b809/docs/decisions/0008-example-badge.png -------------------------------------------------------------------------------- /docs/decisions/0008-example-separate-heading.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adr/madr/be17f6683818534f34b4f4d433c718d46121b809/docs/decisions/0008-example-separate-heading.png -------------------------------------------------------------------------------- /docs/decisions/0008-example-table.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adr/madr/be17f6683818534f34b4f4d433c718d46121b809/docs/decisions/0008-example-table.png -------------------------------------------------------------------------------- /docs/decisions/0009-support-links-between-adrs-inside-an-adrs.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 9 4 | --- 5 | # Support Links To Other ADRs Inside an ADR 6 | 7 | ## Context and Problem Statement 8 | 9 | A decision might point to another decision. 10 | For instance, if a decision is a follow-up to another decision. 11 | This should be supported by MADR, too. 12 | 13 | Technical Story: 14 | 15 | ## Considered Options 16 | 17 | * Include in section "More Information" 18 | * Use tables 19 | * Use heading together with a bullet list directly after status 20 | * Use heading together with a bullet list directly after "Decision Outcome" 21 | * Use heading together with a bullet list at the end 22 | * Do not add links 23 | 24 | ## Decision Outcome 25 | 26 | Chosen option: "Include in section 'More Information'", because comes out best (see below). 27 | 28 | ## Pros and Cons of the Options 29 | 30 | ### Include in section "More Information" 31 | 32 | Example: 33 | 34 | ```markdown 35 | ## More Information 36 | 37 | [ADR-0008](0008-add-status-field.md) reasons on adding meta data (such as status). 38 | ``` 39 | 40 | * Good, because provides freedom to the user 41 | * Bad, because parsing gets harder 42 | 43 | ### Use tables 44 | 45 | * Good, because easy to write 46 | * Good, because history is shown (enabled by concept) 47 | * Good, because [current `adr-tools`' support](https://github.com/npryce/adr-tools/pull/43) uses tables to describe links. 48 | * Bad, because not supported by the CommonMark spec 49 | * Bad, because unclear whether a link was super seeded by another one 50 | * Bad, because valid links not clear at first sight (there might be outdated links shown) 51 | 52 | ### Use heading together with a bullet list directly after status 53 | 54 | Example: 55 | ![grafik](https://user-images.githubusercontent.com/1366654/36787434-6a63e318-1c8a-11e8-8824-4dd7b3d0f2c6.png) 56 | 57 | * Good, because easy to write 58 | * Good, because supported by the CommonMark spec 59 | * Bad, because not consistent with the status label (refs ) 60 | 61 | ### Use heading together with a bullet list directly after "Decision Outcome" 62 | 63 | * Good, because easy to write 64 | * Good, because supported by the CommonMark spec 65 | * Good, because the options are first introduced and then the links 66 | * Good, because consistent with position of "Decision Outcome" 67 | * Bad, because reader might get distracted: He might expect explanation of the options instead of links to something else 68 | * Bad, because not consistent with scientific papers, where related work and future work are coming after the discussion of the content. 69 | 70 | ### Use heading together with a bullet list at the end 71 | 72 | * Good, because easy to write 73 | * Good, because supported by the CommonMark spec 74 | * Good, because the options and pros/cons are kept together with the option list. 75 | * Good, because consistent with pattern format 76 | 77 | ### Do not add links 78 | 79 | * Good, because template stays minimal 80 | -------------------------------------------------------------------------------- /docs/decisions/0010-support-categories.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 10 4 | --- 5 | # Support Categories 6 | 7 | ## Context and Problem Statement 8 | 9 | ADRs are recorded. The number of ADRs grows and the context/topic/scope of ADRs might be different (e.g., frontend, backend) 10 | 11 | ## Decision Drivers 12 | 13 | * Easy to find groups ADRs in hundreds of ADRs 14 | * Easy to group 15 | * Easy to create 16 | * Good finding without external tooling 17 | * Keep newcomers in mind (should be doable in <10 minutes) 18 | * Keep template lean 19 | 20 | ## Considered Options 21 | 22 | * Use labels 23 | * Add `* Category: CATEGORY` directly under the heading (similar to ) 24 | * Use YAML front matter 25 | * Encode category in filename 26 | * Use subfolders with local IDs 27 | * Use subfolders with global IDs 28 | * Don't do it. 29 | 30 | ## Decision Outcome 31 | 32 | Chosen option: "Use subfolders with local IDs", because comes out best (see below). 33 | 34 | ## Pros and Cons of the Options 35 | 36 | ### Use labels 37 | 38 | Example: 39 | 40 | Use Angular ![category-frontend](https://img.shields.io/badge/category-frontend-blue.svg?style=flat-square) 41 | 42 | `![category-frontend](https://img.shields.io/badge/category-frontend-blue.svg?style=flat-square)` 43 | 44 | * Good, because full markdown 45 | * Good, because linking to an overview page is possible (using markdown) 46 | * Bad, because not straight-forward to parse 47 | * Bad, because no simple filtering using `ls` or Windows Explorer is possible 48 | 49 | ### Add `* Category: CATEGORY` directly under the heading 50 | 51 | * Good, because full markdown 52 | * Good, because linking to an overview page is possible (using markdown) 53 | * Good, because straight-forward to parse 54 | * Bad, because no simple filtering using `ls` or Windows Explorer is possible 55 | 56 | ### Use YAML front matter 57 | 58 | Example: 59 | 60 | ```yaml 61 | --- 62 | category: frontend 63 | --- 64 | ``` 65 | 66 | * Good, because nearly straight-forward to parse 67 | * Good, because Jekyll supports it 68 | * Bad, because YAML front matter is not part of the [CommonMarc Spec](http://spec.commonmark.org/) 69 | * Bad, because no simple filtering using `ls` or Windows Explorer is possible 70 | 71 | ### Encode category in filename 72 | 73 | Example: `0050--frontend--title-with-dashes.md` 74 | 75 | * Good, because programmatic filtering is possible 76 | * Good, because `ls -la | grep --category--` works 77 | * Bad, because plain file list in Windows explorer cannot be filtered 78 | * Bad, because as bad as [TagSpaces](https://www.tagspaces.org/), which stores the tags in the filenames in brackets. E.g., `demo[demotag secondtag].md`. 79 | 80 | ### Use subfolders with local IDs 81 | 82 | Optionally "to-be-categorized" folder. 83 | 84 | One level of subfolder, not nested 85 | 86 | #### Examples 87 | 88 | * `docs/decisions/smar/0000-secure-entities.md` 89 | * `docs/decisions/smar/0001-flexible-properties-selection.md` 90 | 91 | #### Pros/cons 92 | 93 | * Good, because grouping is done by folders (which are natural for grouping) 94 | * Good, because typos can easily be spotted 95 | * Bad, because there is no unique number identifying an ADR 96 | * Bad, because two indices have to be maintained (`adr-log` needs to be updated) 97 | * Bad, because [e-adr](https://github.com/adr/e-adr) needs to be adapted to `@ADR("category", number)` (not that bad) 98 | * Bad, because when category is unknown it is hard to find the right folder 99 | * Bad, because using categories might be hampering newcomers 100 | 101 | ### Use subfolders with global IDs 102 | 103 | #### Examples 104 | 105 | * `docs/decisions/smar/0005-secure-entities.md` 106 | * `docs/decisions/smar/0047-flexible-properties-selection.md` 107 | -------------------------------------------------------------------------------- /docs/decisions/0011-use-asterisk-as-list-marker.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 11 4 | --- 5 | # Use Asterisk as List Marker 6 | 7 | ## Context and Problem Statement 8 | 9 | Lists in Markdown can be indicated by `*` (asterisk) or `-` (hyphen). 10 | 11 | ## Considered Options 12 | 13 | * Use an asterisk 14 | * Use a hyphen 15 | 16 | ## Decision Outcome 17 | 18 | Chosen option: "Use an asterisk", because an asterisk does not have a meaning of "good" or "bad", whereas a hyphen `-` could be read as indicator of something negative (in contrast to `+`, which could be more be read as "good"). 19 | 20 | According to the [Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/), an asterisk as list marker is more readable (see [readability profile](http://www.cirosantilli.com/markdown-style-guide/#readability-profile)). 21 | -------------------------------------------------------------------------------- /docs/decisions/0012-use-curly-braces-to-denote-placeholder.md: -------------------------------------------------------------------------------- 1 | --- 2 | parent: Decisions 3 | nav_order: 12 4 | --- 5 | # Use Curly Braces to Denote Placeholders 6 | 7 | ## Context and Problem Statement 8 | 9 | When crafting an ADR placeholders need to be replaced by real values. 10 | How to mark the placeholders? 11 | 12 | ## Considered Options 13 | 14 | * Use curly braces 15 | * Use square brackets 16 | * Use less-than and greater-than 17 | * Use HTML comments 18 | 19 | ## Decision Outcome 20 | 21 | Chosen option: "Use curly braces", because comes out best (see below). 22 | Exception: In the `bare` templates, we use the HTML comment option, because these templates are used by pro users, who are not investigating the HTML for the template, but directly read Markdown. 23 | 24 | ## Pros and Cons of the Options 25 | 26 | ### Use curly braces 27 | 28 | Example: `{option 1}`. 29 | 30 | * Good, because [consistent to mustache templates](https://krasimirtsonev.com/blog/article/markdown-smart-placeholders). 31 | * Good, because no confusion with markdown notation for links. 32 | * Good, because clear distinction between comments on the template usage and placeholders. 33 | 34 | ### Use square brackets 35 | 36 | Example: `[option 1]`. 37 | 38 | * Good, because used in MADR 1.x and MADR 2.x. 39 | * Good, because clear distinction between comments on the template usage and placeholders. 40 | * Bad, because confusion with markdown notation for links. 41 | * Bad, because some users did not remove the brackets. Example: `Date: [2021-03-12]` or `Good, because [user no longer activatess shortcut accidently when entering task]`. 42 | 43 | ### Use less-than and greater-than 44 | 45 | Example: `