diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index 0120005..d3e5ca5 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -23,23 +23,28 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 + with: + show-progress: '' - name: Setup Ruby uses: ruby/setup-ruby@v1 with: - ruby-version: '3.0' # Not needed with a .ruby-version file + ruby-version: '3.1' # Not needed with a .ruby-version file bundler-cache: true # runs 'bundle install' and caches installed gems automatically cache-version: 0 # Increment this number if you need to re-download cached gems - name: Setup Pages id: pages - uses: actions/configure-pages@v1 + uses: actions/configure-pages@v3 - name: Build with Jekyll - uses: actions/jekyll-build-pages@v1 - with: - source: docs/ - destination: ./_site + # Outputs to the './_site' directory by default + run: | + cd docs + bundle install + bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" --destination "../_site" + env: + JEKYLL_ENV: production - name: Upload artifact - uses: actions/upload-pages-artifact@v1 + uses: actions/upload-pages-artifact@v2 deploy: if: github.ref == 'refs/heads/gh-pages' @@ -51,4 +56,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v1 + uses: actions/deploy-pages@v2 diff --git a/.markdownlint.yml b/.markdownlint.yml index b95767e..3cc31c9 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -6,3 +6,5 @@ default: true # # Details: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length MD013: false + +MD033: false diff --git a/CHANGELOG.md b/CHANGELOG.md index 846de00..6371af8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/). +## [Unreleased] + +### Changed + +- Put the content of `status:` in quotes to tell YAML it's a string. [#91](https://github.com/adr/madr/issues/91) +- Renamed "Validation" to "Confirmation" and put it as sub element of "Decision Outcome". [#87](https://github.com/adr/madr/pull/87) + ## [3.0.0] – 2022-10-09 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0adf5e6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,13 @@ +# Contributing to MADR + +- Homepage: Contribute to `gh-pages` branch (using a pull request). + The `docs/` folder of the `gh-pages` branch is the base of the content of . +- Template: Contribute to `develop` branch (using a pull request). + The subdirectory `docs/` will be new homepage of the release. + The current state is rendered at . +- Older version of the template: `develop/v{x}`, where `{x}` is the major version you want to contribute. + In case no such branch exists, contribute to `release/v{x}`. + We will create the respective development branch. + +As soon as a pull request is made, [netlify](https://www.netlify.com/) kicks off a build. +After a successful build, the link to the build is put as a comment to the pull request for inspection. diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 0000000..4c2afd5 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,14 @@ +FROM ruby:2.7 + +ENV LC_ALL C.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US.UTF-8 + +EXPOSE 4000 + +WORKDIR /srv/jekyll +COPY . /srv/jekyll + +RUN gem install bundler && bundle install + +CMD bundle exec jekyll serve -H 0.0.0.0 -t diff --git a/docs/Gemfile b/docs/Gemfile index 6d396ca..9a670a3 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -1,8 +1,7 @@ source 'https://rubygems.org' -gem "jekyll", "~> 4.2" # installed by `gem jekyll` -gem "webrick" # required when using Ruby >= 3 +gem "jekyll", "~> 4.3.2" -gem "just-the-docs", "0.4.0.rc3" +gem "just-the-docs", "0.6.2" -gem "jekyll-remote-theme" +gem 'jekyll-titles-from-headings' diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index ddba171..db31e50 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -1,84 +1,85 @@ GEM remote: https://rubygems.org/ specs: - addressable (2.8.1) + addressable (2.8.5) public_suffix (>= 2.0.2, < 6.0) colorator (1.1.0) - concurrent-ruby (1.1.10) + concurrent-ruby (1.2.2) em-websocket (0.5.3) eventmachine (>= 0.12.9) http_parser.rb (~> 0) eventmachine (1.2.7) ffi (1.15.5) forwardable-extended (2.6.0) + google-protobuf (3.24.3-x86_64-linux) http_parser.rb (0.8.0) - i18n (1.12.0) + i18n (1.14.1) concurrent-ruby (~> 1.0) - jekyll (4.2.2) + jekyll (4.3.2) addressable (~> 2.4) colorator (~> 1.0) em-websocket (~> 0.5) i18n (~> 1.0) - jekyll-sass-converter (~> 2.0) + jekyll-sass-converter (>= 2.0, < 4.0) jekyll-watch (~> 2.0) - kramdown (~> 2.3) + kramdown (~> 2.3, >= 2.3.1) kramdown-parser-gfm (~> 1.0) liquid (~> 4.0) - mercenary (~> 0.4.0) + mercenary (>= 0.3.6, < 0.5) pathutil (~> 0.9) - rouge (~> 3.0) + rouge (>= 3.0, < 5.0) safe_yaml (~> 1.0) - terminal-table (~> 2.0) - jekyll-remote-theme (0.4.3) - addressable (~> 2.0) - jekyll (>= 3.5, < 5.0) - jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) - rubyzip (>= 1.3.0, < 3.0) - jekyll-sass-converter (2.2.0) - sassc (> 2.0.1, < 3.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) jekyll-seo-tag (2.8.0) jekyll (>= 3.8, < 5.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) - just-the-docs (0.4.0.rc3) + just-the-docs (0.6.2) jekyll (>= 3.8.5) + jekyll-include-cache jekyll-seo-tag (>= 2.0) rake (>= 12.3.1) kramdown (2.4.0) rexml kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) - liquid (4.0.3) - listen (3.7.1) + liquid (4.0.4) + listen (3.8.0) rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) mercenary (0.4.0) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (5.0.0) + public_suffix (5.0.3) rake (13.0.6) rb-fsevent (0.11.2) rb-inotify (0.10.1) ffi (~> 1.0) - rexml (3.2.5) - rouge (3.30.0) - rubyzip (2.3.2) + rexml (3.2.6) + rouge (4.1.3) safe_yaml (1.0.5) - sassc (2.4.0) - ffi (~> 1.9) - terminal-table (2.0.0) - unicode-display_width (~> 1.1, >= 1.1.1) - unicode-display_width (1.8.0) - webrick (1.7.0) + sass-embedded (1.63.6) + google-protobuf (~> 3.23) + rake (>= 13.0.0) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.4.2) + webrick (1.8.1) PLATFORMS - x86_64-linux-musl + x86_64-linux DEPENDENCIES - jekyll (~> 4.2) - jekyll-remote-theme - just-the-docs (= 0.4.0.rc3) - webrick + jekyll (~> 4.3.2) + jekyll-titles-from-headings + just-the-docs (= 0.6.2) BUNDLED WITH - 2.2.24 + 2.4.19 diff --git a/docs/README.md b/docs/README.md index 99e2315..e8f0339 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,7 +19,11 @@ and go to in your browser. On **Windows**, using a dockerized environment is recommended: ```terminal -docker run -p 4000:4000 -it --rm --volume="C:\git-repositories\madr\docs":/srv/jekyll jekyll/jekyll:4 jekyll serve +docker build . -t madrjekyll +docker run -p 4000:4000 -it --rm --volume="C:\git-repositories\madr\docs":/srv/jekyll madrjekyll jekyll serve -H 0.0.0.0 -t ``` -In case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and rerun. +* With Ctrl+C you can stop the server (this is enabled by the `-it` switch). +* In case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and rerun. +* The current `Dockerfile` is based on . + The [Jekyll Docker image](https://github.com/envygeeks/jekyll-docker#jekyll-docker) did not work end of 20222 (because Ruby was too new). diff --git a/docs/_config.yml b/docs/_config.yml index 86b9633..994bf77 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,8 +1,18 @@ +title: "MADR" +desription: Markdown Any Decisions Records repository: adr/madr -title: "Any Decisions Records" -remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3 +theme: just-the-docs color_scheme: light +defaults: + - + scope: + path: "**/*.md" + values: + layout: "page" + +exclude: [Dockerfile, README.md, Gemfile, Gemfile.lock] + # Hint by https://github.com/just-the-docs/just-the-docs/issues/374#issuecomment-680273258 # Theme read from https://github.com/StylishThemes/Syntax-Themes/blob/master/pygments/css-github/ # Browse alternative themes at https://stylishthemes.github.io/Syntax-Themes/pygments/ @@ -28,8 +38,8 @@ gh_edit_view_mode: "edit" # ga_tracking: UA-5555555-55 # ga_tracking_anonymize_ip: true -baseurl: "/madr" +baseurl: "" url: "https://adr.github.io" plugins: - - jekyll-remote-theme + - jekyll-titles-from-headings diff --git a/docs/decisions/0012-use-curly-brackets-to-denote-placeholder.md b/docs/decisions/0012-use-curly-braces-to-denote-placeholder.md similarity index 96% rename from docs/decisions/0012-use-curly-brackets-to-denote-placeholder.md rename to docs/decisions/0012-use-curly-braces-to-denote-placeholder.md index 1121e44..c73921b 100644 --- a/docs/decisions/0012-use-curly-brackets-to-denote-placeholder.md +++ b/docs/decisions/0012-use-curly-braces-to-denote-placeholder.md @@ -2,7 +2,7 @@ parent: Decisions nav_order: 12 --- -# Use Curly Brackets to Denote Placeholders +# Use Curly Braces to Denote Placeholders ## Context and Problem Statement diff --git a/docs/decisions/0018-use-confirmation-as-heading.md b/docs/decisions/0018-use-confirmation-as-heading.md new file mode 100644 index 0000000..230f4f5 --- /dev/null +++ b/docs/decisions/0018-use-confirmation-as-heading.md @@ -0,0 +1,30 @@ +--- +parent: Decisions +nav_order: 18 +--- + + +# Use "Confirmation" as Heading + +## Context and Problem Statement + +In MADR, we want to include some sort of check that the decision was implemented. +How to name the heading for the explanation? + +## Decision Drivers + +* Consistent with terms used in IT +* Common word + +## Considered Options + +* "Confirmation" +* "Validation" +* "Verification" + +## Decision Outcome + +Chosen option: "Confirmation", because "validation" is out of scope of the template. +There is a process leading to a "valid" ADR. +The other term "Verification" is often bound to a formal tool or formal procedure. +We wanted to enable also less formal checks. diff --git a/docs/decisions/adr-template.md b/docs/decisions/adr-template.md index 5995292..dd410b7 100644 --- a/docs/decisions/adr-template.md +++ b/docs/decisions/adr-template.md @@ -5,7 +5,7 @@ nav_order: 100 title: ADR Template # These are optional elements. Feel free to remove any of them. -# status: {proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)} +# status: "{proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)}" # date: {YYYY-MM-DD when the decision was last updated} # deciders: {list everyone involved in the decision} # consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication} @@ -47,9 +47,10 @@ Chosen option: "{title of option 1}", because * … -## Validation +### Confirmation -{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test} +{Describe how the implementation of/compliance with the ADR is confirmed. E.g., by a review or an ArchUnit test. + Although we classify this element as optional, it is included in most ADRs.} ## Pros and Cons of the Options @@ -81,6 +82,5 @@ Chosen option: "{title of option 1}", because {You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or - define when this decision when and how the decision should be realized and if/when it should be re-visited and/or - how the decision is validated. - Links to other decisions and resources might here appear as well.} + define when/how this decision should be realized and if/when it should be re-visited. +Links to other decisions and resources might appear here as well.} diff --git a/docs/decisions/index.md b/docs/decisions/index.md index 6478438..1107b37 100644 --- a/docs/decisions/index.md +++ b/docs/decisions/index.md @@ -4,7 +4,7 @@ nav_order: 100 --- # Decisions -Below, all any decision records for MADR are listed. +Below, all decision records for MADR are listed. This list uses the TOC functionality of the [Just the Docs Jekyll template](https://just-the-docs.github.io/just-the-docs/). For new ADRs, please use [adr-template.md](adr-template.md) as basis. diff --git a/docs/examples.md b/docs/examples.md index 6e9160c..73e0ec1 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -9,7 +9,7 @@ The following sections present an example in the context of assertion frameworks We start with presenting a very short and dense version: It "just" lists the context and problem statement, the available options, and the outcome. For some decisions, these bits of information could not be enough. -Therfore, it is possible to "unpack" the decision. +Therefore, it is possible to "unpack" the decision. This is done in the presented longer version of the ADR. ## Short Version diff --git a/docs/index.md b/docs/index.md index 40aeb09..408425f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,8 @@ --- nav_order: 1 +title: About MADR --- + # Markdown Any Decision Records [![part of ADR](https://img.shields.io/badge/part_of-ADR-blue.svg)](https://adr.github.io) > "Markdown Any Decision Records" (MADR) `[ˈmæɾɚ]` – decisions that [matter `[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation). @@ -23,6 +25,7 @@ The template originated from capturing architectural decisions and developed to ## News +* 2023-04-05: Two new Medium stories ["How to create Architectural Decision Records (ADRs) — and how not to"](https://medium.com/olzzio/how-to-create-architectural-decision-records-adrs-and-how-not-to-93b5b4b33080) and ["How to review Architectural Decision Records (ADRs) — and how not to"](https://medium.com/olzzio/how-to-review-architectural-decision-records-adrs-and-how-not-to-2707652db196). Metaphors, patterns, anti-patterns, checklists applicable (but not limited) to MADRs. * 2022-11-22. MADR Version 1.0 was released five years ago. A new blog post ["The Markdown ADR (MADR) Template Explained and Distilled"](https://medium.com/olzzio/the-markdown-adr-madr-template-explained-and-distilled-b67603ec95bb) is available on Medium. * 2022-10-09: Release of MADR 3.0.0.\ The most important change is the merged of sections "Positive Consequences" and "Negative Consequences" into "Consequences" to enable similar grammar as in "Pros and Cons of the Options". @@ -48,7 +51,7 @@ It should be as easy as possible to a) write down the decisions and b) to version the decisions. -There are debates what is an architecturally-significant decision and which decisions are not architecturally significant. +There are debates about what is an architecturally-significant decision and which decisions are not architecturally significant. Since we believe that any (important) decision should be captured in a structured way, we offer the MADR template to capture any decision. This repository offers a solution to record any decisions. diff --git a/template/adr-template.md b/template/adr-template.md index 8ec0052..1cfb4c6 100644 --- a/template/adr-template.md +++ b/template/adr-template.md @@ -1,6 +1,6 @@ --- # These are optional elements. Feel free to remove any of them. -status: {proposed | rejected | accepted | deprecated | … | superseded by ADR-0005 <0005-example.md>} +status: "{proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)}" date: {YYYY-MM-DD when the decision was last updated} deciders: {list everyone involved in the decision} consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication} @@ -40,9 +40,10 @@ Chosen option: "{title of option 1}", because * … -## Validation +### Confirmation -{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test} +{Describe how the implementation of/compliance with the ADR is confirmed. E.g., by a review or an ArchUnit test. + Although we classify this element as optional, it is included in most ADRs.} ## Pros and Cons of the Options @@ -74,6 +75,5 @@ Chosen option: "{title of option 1}", because {You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or - define when and how this decision should be realized and if/when it should be re-visited and/or - how the decision is validated. - Links to other decisions and resources might appear here as well.} + define when/how this decision the decision should be realized and if/when it should be re-visited. +Links to other decisions and resources might appear here as well.}