Prepare release 4.0.0-beta (#152)

Author: koppor

CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [4.0.0-beta] – 2024-09-02
 
 ### Added
 
@@ -217,7 +217,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 First release of Markdown Architectural Decision Records.
 
-[Unreleased]: https://github.com/adr/madr/compare/3.0.0...develop
+[4.0.0-beta]: https://github.com/adr/madr/compare/3.0.0...4.0.0-beta
 [3.0.0]: https://github.com/adr/madr/compare/3.0.0-beta.2...3.0.0
 [3.0.0-beta.2]: https://github.com/adr/madr/compare/3.0.0-beta...3.0.0-beta.2
 [3.0.0-beta]: https://github.com/adr/madr/compare/2.1.2...3.0.0-beta

README.md

@@ -81,7 +81,7 @@ In case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and
 3. Commit ("Update examples and decisions") and push. Possibly as pull request.
 4. Adapt the version reference in `template/0000-use-madr.md`.
 5. Update "template" files in in `docs/decisions/`
-   * Copy `template/0000-use-madr.md` to `docs/decisions/0000-use-madr.md`.
+   * Copy `template/0000-use-markdown-architectural-decision-records.md` to `docs/decisions/0000-use-markdown-architectural-decision-records.md`.
    * Adapt content of `docs/decisions/adr-template.md` based on `template/adr-template.md`.
      Thereby, ensure that the YAML front matter in `docs/decisions/adr-template.md` is kept.
 6. Add link to `docs/index.md` at "Older versions" (for the homepage).

docs/decisions/0000-use-madr.md renamed to docs/decisions/0000-use-markdown-architectural-decision-records.md

@@ -1,7 +1,3 @@
----
-parent: Decisions
-nav_order: 0
----
 # Use Markdown Architectural Decision Records
 
 ## Context and Problem Statement
@@ -23,7 +19,7 @@ Chosen option: "MADR 4.0.0", because
 
 * Implicit assumptions should be made explicit.
   Design documentation is important to enable people understanding the decisions later on.
-  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+  See also ["A rational design process: How and why to fake it"](https://doi.org/10.1109/TSE.1986.6312940).
 * MADR allows for structured capturing of any decision.
 * The MADR format is lean and fits our development style.
 * The MADR structure is comprehensible and facilitates usage & maintenance.

docs/decisions/adr-template.md

@@ -13,12 +13,11 @@ title: ADR Template
 ---
 <!-- 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 -->
-# {short title of solved problem and solution}
+# {short title, representative of solved problem and found solution}
 
 ## Context and Problem Statement
 
-{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
- You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
+{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
 
 <!-- This is an optional element. Feel free to remove. -->
 ## Decision Drivers
@@ -36,8 +35,7 @@ title: ADR Template
 
 ## Decision Outcome
 
-Chosen option: "{title of option 1}", because
-{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
+Chosen option: {title of option 1}, because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
 
 <!-- This is an optional element. Feel free to remove. -->
 ### Consequences
@@ -49,8 +47,7 @@ Chosen option: "{title of option 1}", because
 <!-- This is an optional element. Feel free to remove. -->
 ### Confirmation
 
-{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.}
+{Describe how the implementation of/compliance with the ADR can/will be confirmed. Are the design that was decided for and its implementation in line with the decision made? E.g., a design/code review or a test with a library such as ArchUnit can help validate this. Not that although we classify this element as optional, it is included in many ADRs.}
 
 <!-- This is an optional element. Feel free to remove. -->
 ## Pros and Cons of the Options
@@ -80,7 +77,4 @@ Chosen option: "{title of option 1}", because
 <!-- This is an optional element. Feel free to remove. -->
 ## More Information
 
-{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 should be realized and if/when it should be re-visited.
-Links to other decisions and resources might appear here as well.}
+{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. Links to other decisions and resources might appear here as well.}