index page updated

.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

.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

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

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 <https://adr.github.io/madr/>.
+- 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 <https://develop--madr-develop.netlify.app/>.
+- 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.

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

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'

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

docs/README.md

@@ -19,7 +19,11 @@ and go to <http://localhost:4000/> 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 <kbd>Ctrl</kbd>+<kbd>C</kbd> 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 <https://github.com/just-the-docs/just-the-docs/blob/main/Dockerfile>.
+  The [Jekyll Docker image](https://github.com/envygeeks/jekyll-docker#jekyll-docker) did not work end of 20222 (because Ruby was too new).

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/[email protected]
+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

docs/decisions/0012-use-curly-brackets-to-denote-placeholder.md → 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
 

docs/decisions/0018-use-confirmation-as-heading.md

@@ -0,0 +1,30 @@
+---
+parent: Decisions
+nav_order: 18
+---
+<!-- we need to disable MD025, because we use the different heading "ADR Template" in the homepage (see above) than it is foreseen in the template -->
+<!-- markdownlint-disable-next-line MD025 -->
+# 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.

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
 * … <!-- numbers of consequences can vary -->
 
 <!-- This is an optional element. Feel free to remove. -->
-## 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.}
 
 <!-- This is an optional element. Feel free to remove. -->
 ## 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.}

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.

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

docs/index.md

@@ -1,6 +1,8 @@
 ---
 nav_order: 1
+title: About MADR
 ---
+<!-- markdownlint-disable MD025 -->
 # 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.