From 3360cf586f6897ef2debd767f16b3c4b3878dd20 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Wed, 19 Apr 2023 17:20:55 +0200 Subject: [PATCH 01/16] Update just-the-docs to v0.5.0 --- docs/Gemfile | 2 +- docs/Gemfile.lock | 4 ++-- docs/_config.yml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/Gemfile b/docs/Gemfile index 6d396ca..41f3e28 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -3,6 +3,6 @@ source 'https://rubygems.org' gem "jekyll", "~> 4.2" # installed by `gem jekyll` gem "webrick" # required when using Ruby >= 3 -gem "just-the-docs", "0.4.0.rc3" +gem "just-the-docs", "0.5.0" gem "jekyll-remote-theme" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index ddba171..ccedd3c 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -40,7 +40,7 @@ GEM jekyll (>= 3.8, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) - just-the-docs (0.4.0.rc3) + just-the-docs (0.5.0) jekyll (>= 3.8.5) jekyll-seo-tag (>= 2.0) rake (>= 12.3.1) @@ -77,7 +77,7 @@ PLATFORMS DEPENDENCIES jekyll (~> 4.2) jekyll-remote-theme - just-the-docs (= 0.4.0.rc3) + just-the-docs (= 0.5.0) webrick BUNDLED WITH diff --git a/docs/_config.yml b/docs/_config.yml index 86b9633..c135519 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,6 +1,6 @@ repository: adr/madr title: "Any Decisions Records" -remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3 +remote_theme: just-the-docs/just-the-docs@v0.5.0 color_scheme: light # Hint by https://github.com/just-the-docs/just-the-docs/issues/374#issuecomment-680273258 From d3d795f22434d4974ed403f00774de1de866ca47 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Wed, 19 Apr 2023 17:57:28 +0200 Subject: [PATCH 02/16] Fix update --- docs/Gemfile | 2 -- docs/Gemfile.lock | 7 ------- docs/_config.yml | 19 +++++++++++++------ 3 files changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/Gemfile b/docs/Gemfile index 41f3e28..4e248eb 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -4,5 +4,3 @@ gem "jekyll", "~> 4.2" # installed by `gem jekyll` gem "webrick" # required when using Ruby >= 3 gem "just-the-docs", "0.5.0" - -gem "jekyll-remote-theme" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index ccedd3c..7d06320 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -29,11 +29,6 @@ GEM rouge (~> 3.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) jekyll-seo-tag (2.8.0) @@ -62,7 +57,6 @@ GEM ffi (~> 1.0) rexml (3.2.5) rouge (3.30.0) - rubyzip (2.3.2) safe_yaml (1.0.5) sassc (2.4.0) ffi (~> 1.9) @@ -76,7 +70,6 @@ PLATFORMS DEPENDENCIES jekyll (~> 4.2) - jekyll-remote-theme just-the-docs (= 0.5.0) webrick diff --git a/docs/_config.yml b/docs/_config.yml index c135519..3111bd2 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.5.0 +theme: just-the-docs color_scheme: light +exclude: [README.md] + +defaults: + - + scope: + path: "**/*.md" + values: + layout: "page" + # 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,5 @@ 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 From 5357f37246cbe7cd97d68d232df658e0f8d891a7 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Wed, 19 Apr 2023 18:03:16 +0200 Subject: [PATCH 03/16] Initial CONTIRBUTING.md --- CONTRIBUTING.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b8b9db9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# 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. +- 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. From 33d7620f701fb508ebe37850f2ce9e76c3b31b37 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Fri, 21 Apr 2023 08:58:27 +0200 Subject: [PATCH 04/16] Put the content of `status:` in quotes (#94) --- CHANGELOG.md | 6 ++++++ docs/decisions/adr-template.md | 2 +- template/adr-template.md | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 846de00..2a077d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,12 @@ 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) + ## [3.0.0] – 2022-10-09 ### Added diff --git a/docs/decisions/adr-template.md b/docs/decisions/adr-template.md index 5995292..5bc32fa 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} diff --git a/template/adr-template.md b/template/adr-template.md index 8ec0052..f084998 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} From 17836a2087f495bacb26d3ec3bb8c47f1e9d6d83 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Thu, 27 Apr 2023 00:12:13 +0200 Subject: [PATCH 05/16] Get local build running --- docs/Dockerfile | 14 +++++++++++++ docs/Gemfile | 2 ++ docs/Gemfile.lock | 52 ++++++++++++++++++++++++++--------------------- docs/README.md | 8 ++++++-- docs/_config.yml | 7 +++++-- docs/index.md | 1 + 6 files changed, 57 insertions(+), 27 deletions(-) create mode 100644 docs/Dockerfile 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 4e248eb..e67edd6 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -4,3 +4,5 @@ gem "jekyll", "~> 4.2" # installed by `gem jekyll` gem "webrick" # required when using Ruby >= 3 gem "just-the-docs", "0.5.0" + +gem 'jekyll-titles-from-headings' diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 7d06320..b415a0e 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -1,38 +1,42 @@ GEM remote: https://rubygems.org/ specs: - addressable (2.8.1) + addressable (2.8.4) 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.22.3-x86_64-linux) http_parser.rb (0.8.0) - i18n (1.12.0) + i18n (1.13.0) 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-sass-converter (2.2.0) - sassc (> 2.0.1, < 3.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + 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.5.0) @@ -43,35 +47,37 @@ GEM 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.1) 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) + rouge (4.1.0) 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.62.1) + google-protobuf (~> 3.21) + rake (>= 10.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-titles-from-headings just-the-docs (= 0.5.0) webrick BUNDLED WITH - 2.2.24 + 2.4.12 diff --git a/docs/README.md b/docs/README.md index 99e2315..a3765fc 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). \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml index 3111bd2..994bf77 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -4,8 +4,6 @@ repository: adr/madr theme: just-the-docs color_scheme: light -exclude: [README.md] - defaults: - scope: @@ -13,6 +11,8 @@ defaults: 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/ @@ -40,3 +40,6 @@ gh_edit_view_mode: "edit" baseurl: "" url: "https://adr.github.io" + +plugins: + - jekyll-titles-from-headings diff --git a/docs/index.md b/docs/index.md index 40aeb09..c7f2368 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,6 @@ --- 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) From 7825e6a44429268b42299dd010872d0ba612bd91 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Thu, 27 Apr 2023 00:28:05 +0200 Subject: [PATCH 06/16] Fix build --- .github/workflows/pages.yaml | 15 +++++++++------ .markdownlint.yml | 2 ++ docs/README.md | 2 +- docs/index.md | 1 + 4 files changed, 13 insertions(+), 7 deletions(-) diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index 0120005..9f85b93 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -27,17 +27,20 @@ jobs: - 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@v2 - 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 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/docs/README.md b/docs/README.md index a3765fc..e8f0339 100644 --- a/docs/README.md +++ b/docs/README.md @@ -26,4 +26,4 @@ docker run -p 4000:4000 -it --rm --volume="C:\git-repositories\madr\docs":/srv/j * 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). \ No newline at end of file + 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/index.md b/docs/index.md index c7f2368..a8c3061 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,7 @@ 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). From 06f2b0b09ad8aac191b5bc4faacb21db63f26672 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Thu, 27 Apr 2023 09:28:58 +0200 Subject: [PATCH 07/16] Update just-the-docs to 0.5.1 --- docs/Gemfile | 2 +- docs/Gemfile.lock | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Gemfile b/docs/Gemfile index e67edd6..69f9e82 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -3,6 +3,6 @@ source 'https://rubygems.org' gem "jekyll", "~> 4.2" # installed by `gem jekyll` gem "webrick" # required when using Ruby >= 3 -gem "just-the-docs", "0.5.0" +gem "just-the-docs", "0.5.1" gem 'jekyll-titles-from-headings' diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index b415a0e..7135eb1 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -39,7 +39,7 @@ GEM jekyll (>= 3.3, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) - just-the-docs (0.5.0) + just-the-docs (0.5.1) jekyll (>= 3.8.5) jekyll-seo-tag (>= 2.0) rake (>= 12.3.1) @@ -76,7 +76,7 @@ PLATFORMS DEPENDENCIES jekyll (~> 4.2) jekyll-titles-from-headings - just-the-docs (= 0.5.0) + just-the-docs (= 0.5.1) webrick BUNDLED WITH From b211f315f0f91f2e21df415db6b1cf483dd82f24 Mon Sep 17 00:00:00 2001 From: Doc SoC Date: Thu, 4 May 2023 15:34:14 +0200 Subject: [PATCH 08/16] Links to ADR creation and review posts --- docs/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index a8c3061..3fed670 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,7 +25,8 @@ The template originated from capturing architectural decisions and developed to ## News -* 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. +* 2023-05-05: Two new blog posts discuss how to [create](https://medium.com/olzzio/how-to-create-architectural-decision-records-adrs-and-how-not-to-93b5b4b33080) and how to [review](https://medium.com/olzzio/how-to-review-architectural-decision-records-adrs-and-how-not-to-2707652db196) ADRs (and how not to). MADR is referenced in both. +* 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". [[Full Changelog](https://github.com/adr/madr/blob/main/CHANGELOG.md#300--2022-10-09)] From a781c47f70b8ba79d22f8652c9880e5003ee6337 Mon Sep 17 00:00:00 2001 From: Doc SoC Date: Thu, 4 May 2023 15:38:59 +0200 Subject: [PATCH 09/16] Linter finding fixed --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 3fed670..41d20b8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,7 +25,7 @@ The template originated from capturing architectural decisions and developed to ## News -* 2023-05-05: Two new blog posts discuss how to [create](https://medium.com/olzzio/how-to-create-architectural-decision-records-adrs-and-how-not-to-93b5b4b33080) and how to [review](https://medium.com/olzzio/how-to-review-architectural-decision-records-adrs-and-how-not-to-2707652db196) ADRs (and how not to). MADR is referenced in both. +* 2023-05-05: Two new blog posts discuss how to [create](https://medium.com/olzzio/how-to-create-architectural-decision-records-adrs-and-how-not-to-93b5b4b33080) and how to [review](https://medium.com/olzzio/how-to-review-architectural-decision-records-adrs-and-how-not-to-2707652db196) ADRs (and how not to). MADR is referenced in both. * 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". From 21aa3016aad7085a285ea614b95653651c74a8bf Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Fri, 16 Jun 2023 15:47:07 +0200 Subject: [PATCH 10/16] Fix validation (#87) Co-authored-by: Doc SoC --- CHANGELOG.md | 1 + .../0018-use-confirmation-as-heading.md | 30 +++++++++++++++++++ docs/decisions/adr-template.md | 10 +++---- template/adr-template.md | 10 +++---- 4 files changed, 41 insertions(+), 10 deletions(-) create mode 100644 docs/decisions/0018-use-confirmation-as-heading.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2a077d8..6371af8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ### 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 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 5bc32fa..74fb09a 100644 --- a/docs/decisions/adr-template.md +++ b/docs/decisions/adr-template.md @@ -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 the 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/template/adr-template.md b/template/adr-template.md index f084998..1cfb4c6 100644 --- a/template/adr-template.md +++ b/template/adr-template.md @@ -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.} From 17d7e2107d68d8f7f3be052fea8c9c6641bcdd10 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Thu, 31 Aug 2023 08:40:39 +0200 Subject: [PATCH 11/16] Fix title of ADR-0012 --- ...holder.md => 0012-use-curly-braces-to-denote-placeholder.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/decisions/{0012-use-curly-brackets-to-denote-placeholder.md => 0012-use-curly-braces-to-denote-placeholder.md} (96%) 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 From 99a706e6cf1ce3ec066d230606580d321d77c538 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Wed, 20 Sep 2023 19:23:08 +0200 Subject: [PATCH 12/16] Add hint on netlify --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b8b9db9..0adf5e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,10 @@ 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. From e4bf2926a48063d7ff2b8a7403aae94a4447a2d7 Mon Sep 17 00:00:00 2001 From: omahs <73983677+omahs@users.noreply.github.com> Date: Wed, 20 Sep 2023 19:24:57 +0200 Subject: [PATCH 13/16] Fix minor typos (#105) --- docs/decisions/adr-template.md | 2 +- docs/decisions/index.md | 2 +- docs/examples.md | 2 +- docs/index.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/decisions/adr-template.md b/docs/decisions/adr-template.md index 74fb09a..dd410b7 100644 --- a/docs/decisions/adr-template.md +++ b/docs/decisions/adr-template.md @@ -82,5 +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/how this decision the decision should be realized and if/when it should be re-visited. + 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 41d20b8..5039135 100644 --- a/docs/index.md +++ b/docs/index.md @@ -51,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. From d0b469adb0d140970b3351f775dae27f52ce7d59 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Wed, 20 Sep 2023 19:40:33 +0200 Subject: [PATCH 14/16] Port news from gh-pages to develop branch --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 5039135..cf4971a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,8 +25,8 @@ The template originated from capturing architectural decisions and developed to ## News -* 2023-05-05: Two new blog posts discuss how to [create](https://medium.com/olzzio/how-to-create-architectural-decision-records-adrs-and-how-not-to-93b5b4b33080) and how to [review](https://medium.com/olzzio/how-to-review-architectural-decision-records-adrs-and-how-not-to-2707652db196) ADRs (and how not to). MADR is referenced in both. -* 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. +* 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". [[Full Changelog](https://github.com/adr/madr/blob/main/CHANGELOG.md#300--2022-10-09)] From ab203aac5e748dcceddba9715ba6dd9d98ebd040 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Wed, 20 Sep 2023 19:42:30 +0200 Subject: [PATCH 15/16] Fix linting issue --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index cf4971a..408425f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,7 +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. +* 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". From efa198e3bbdb4acf0fe41acd56febbc9a732c9ab Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Wed, 20 Sep 2023 20:11:27 +0200 Subject: [PATCH 16/16] Update dependencies (#108) --- .github/workflows/pages.yaml | 10 ++++++---- docs/Gemfile | 5 ++--- docs/Gemfile.lock | 30 ++++++++++++++++-------------- 3 files changed, 24 insertions(+), 21 deletions(-) diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index 9f85b93..d3e5ca5 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -23,7 +23,9 @@ 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: @@ -32,7 +34,7 @@ jobs: cache-version: 0 # Increment this number if you need to re-download cached gems - name: Setup Pages id: pages - uses: actions/configure-pages@v2 + uses: actions/configure-pages@v3 - name: Build with Jekyll # Outputs to the './_site' directory by default run: | @@ -42,7 +44,7 @@ jobs: 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' @@ -54,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/docs/Gemfile b/docs/Gemfile index 69f9e82..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.5.1" +gem "just-the-docs", "0.6.2" gem 'jekyll-titles-from-headings' diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 7135eb1..db31e50 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -1,7 +1,7 @@ GEM remote: https://rubygems.org/ specs: - addressable (2.8.4) + addressable (2.8.5) public_suffix (>= 2.0.2, < 6.0) colorator (1.1.0) concurrent-ruby (1.2.2) @@ -11,9 +11,9 @@ GEM eventmachine (1.2.7) ffi (1.15.5) forwardable-extended (2.6.0) - google-protobuf (3.22.3-x86_64-linux) + google-protobuf (3.24.3-x86_64-linux) http_parser.rb (0.8.0) - i18n (1.13.0) + i18n (1.14.1) concurrent-ruby (~> 1.0) jekyll (4.3.2) addressable (~> 2.4) @@ -31,6 +31,8 @@ GEM safe_yaml (~> 1.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) @@ -39,8 +41,9 @@ GEM jekyll (>= 3.3, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) - just-the-docs (0.5.1) + 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) @@ -54,17 +57,17 @@ GEM mercenary (0.4.0) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (5.0.1) + 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 (4.1.0) + rexml (3.2.6) + rouge (4.1.3) safe_yaml (1.0.5) - sass-embedded (1.62.1) - google-protobuf (~> 3.21) - rake (>= 10.0.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) @@ -74,10 +77,9 @@ PLATFORMS x86_64-linux DEPENDENCIES - jekyll (~> 4.2) + jekyll (~> 4.3.2) jekyll-titles-from-headings - just-the-docs (= 0.5.1) - webrick + just-the-docs (= 0.6.2) BUNDLED WITH - 2.4.12 + 2.4.19