Updated to MADR 2.0.3

src/_adr_add_link_madr

@@ -7,19 +7,26 @@ link_type="${2:?LINK TYPE}"
 target=$("$adr_bin_dir/_adr_file" "${3:?TARGET}")
 
 target_title="$("$adr_bin_dir/_adr_title" "$target")"
-updated_status="| $date | $link_type [$target_title]($(basename $target)) |"
-awk -v updated_status="$updated_status" '
-	BEGIN { 
-		in_status_section=0
-	}
-	/^\|.*\|$/ {
-        in_status_section=1
-	}
-	in_status_section && /^\s*$/ {
-        print updated_status
-		in_status_section=0 
-	}
-	{ print }
-' "$source" > "$source.tmp"
+updated_status="$link_type [$target_title]($(basename $target))"
 
-mv "$source.tmp" "$source"
+if [ "$link_type" != "Supercedes" ] 
+then
+awk -v n=3 -v s="* Status: $updated_status" '(NR==n) { print s }{ print } ' "$source" > "$source.tmp" && mv "$source.tmp" "$source"
+fi
+
+if [ "$link_type" == "Superceded by" ]
+then
+sed -e "s/\* Date:.*/\* Date: $date/" "$source" > "$source.tmp" && mv "$source.tmp" "$source"
+fi
+
+if grep -q "## Links" "$source"; then
+    cat <<EOT >> "$source"
+* $updated_status
+EOT
+else
+    cat <<EOT >> "$source"
+## Links
+
+* $updated_status
+EOT
+fi

src/_adr_links

@@ -2,4 +2,4 @@
 set -e
 eval "$($(dirname $0)/adr-config)"
 
-sed 's/^| [-0-9]* | //' "$("$adr_bin_dir/_adr_file" "$1")" | sed 's/ |$//'| sed -n -E 's/^([a-zA-Z ]+) \[.*\]\(0*([1-9][0-9]*).*\)/\2=\1/p'  
+sed 's/^\* //' "$("$adr_bin_dir/_adr_file" "$1")" | sed -n '/Status:/!p' | sed -n -E 's/^([a-zA-Z ]+) \[.*\]\(0*([1-9][0-9]*).*\)/\2=\1/p'  

src/_adr_remove_status_madr

@@ -1,6 +1,8 @@
 #!/bin/bash
 set -e
 eval "$($(dirname $0)/adr-config)"
-#This is empty because madr doesn't actually remove a status ever, but this dummy is necessary because of how superceding is handled
-
 
+current_status=${1:?FROM}
+file=$("$adr_bin_dir/_adr_file" "${2:?FILE}")
+pattern="* Status: $current_status"
+sed -n "/\* Status: $current_status/!p" "$file" > temp && mv temp "$file"

src/adr-new

@@ -130,11 +130,12 @@ case $type in
     -e "s|STATUS|Accepted|" \
     > $dstfile
     ;;
-# Date and Status are not contained in template, but should be added when ADR is created
     madr)
-    cat $template | sed -e "s/\[short title of solved problem and solution\]/$title/" > $tempfile
-    awk -v n=2 -v s="\n| Date | Status |\n| -- | -- |\n| $date | Accepted |" 'NR == n {print s} {print}' $tempfile > $dstfile
-    rm $tempfile
+    cat $template | sed \
+    -e "s/\[short title of solved problem and solution\]/$title/" \
+    -e "s/\* Status: \[accepted | superseeded by \[ADR-0005\](0005-example.md) | deprecated | …\] <!-- optional -->/\* Status: Accepted/" \
+    -e "s/\* Date: \[YYYY-MM-DD when the decision was last updated\] <!-- optional -->/\* Date: $date/" \
+    > $dstfile
     ;;
 esac
 

src/init-madr.md

@@ -1,23 +1,25 @@
 # Use Markdown Architectural Decision Records
 
-Should we record the architectural decisions made in this project?
-And if we do, how to structure these recordings?
+## Context and Problem Statement
 
-## Considered Alternatives
+We want to record architectural decisions made in this project.
+Which format and structure should these records follow?
 
-* [MADR](https://adr.github.io/madr/) - Markdown Architectural Decision Records
-* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) - The first incarnation of the term "ADR". Maintainable by [adr-tools](https://github.com/npryce/adr-tools).
+## Considered Options
+
+* [MADR](https://adr.github.io/madr/) 2.0.3 - The Markdown Architectural Decision Records
+* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) - The first incarnation of the term "ADR"
 * [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) - The Y-Statements
-* [DecisionRecord](https://github.com/schubmat/DecisionCapture) - Agile records by [@schubmat](https://github.com/schubmat/)
 * Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
-* No records
+* Formless - No conventions for file format and structure
 
 ## Decision Outcome
 
-* Chosen Alternative: MADR
+Chosen option: "MADR 2.0.3", 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).
-* The MADR template is lean and fits our development style.
-
-<!-- Pros and cons of alternatives straight-forward to elicit and therefore not captured. -->
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.
+* Version 2.0.3 is the latest one available when starting to document ADRs.

src/template-madr.md

@@ -1,48 +1,70 @@
 # [short title of solved problem and solution]
 
-User Story: [ticket/issue-number] <!-- optional -->
+* Status: [accepted | superseeded by [ADR-0005](0005-example.md) | deprecated | …] <!-- optional -->
+* Deciders: [list everyone involved in the decision] <!-- optional -->
+* Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->
 
-[context and problem statement]
-[decision drivers | forces | facing] <!-- optional -->
+Technical Story: [description | ticket/issue URL] <!-- optional -->
+
+## Context and Problem Statement
+
+[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
+
+## Decision Drivers <!-- optional -->
+
+* [driver 1, e.g., a force, facing concern, …]
+* [driver 2, e.g., a force, facing concern, …]
+* … <!-- numbers of drivers can vary -->
 
 ## Considered Options
 
 * [option 1]
 * [option 2]
 * [option 3]
-* ... <!-- numbers of options can vary -->
+* … <!-- numbers of options can vary -->
 
 ## Decision Outcome
 
-Chosen option: [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: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].
 
 Positive Consequences: <!-- optional -->
-  - [e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...]
-  - ...
+* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
+* …
 
 Negative consequences: <!-- optional -->
-  - [e.g., compromising quality attribute, follow-up decisions required, ...]
-  - ...
+* [e.g., compromising quality attribute, follow-up decisions required, …]
+* …
 
 ## Pros and Cons of the Options <!-- optional -->
 
 ### [option 1]
 
+[example | description | pointer to more information | …] <!-- optional -->
+
 * Good, because [argument a]
 * Good, because [argument b]
 * Bad, because [argument c]
-* ... <!-- numbers of pros and cons can vary -->
+* … <!-- numbers of pros and cons can vary -->
 
 ### [option 2]
 
+[example | description | pointer to more information | …] <!-- optional -->
+
 * Good, because [argument a]
 * Good, because [argument b]
 * Bad, because [argument c]
-* ... <!-- numbers of pros and cons can vary -->
+* … <!-- numbers of pros and cons can vary -->
 
 ### [option 3]
 
+[example | description | pointer to more information | …] <!-- optional -->
+
 * Good, because [argument a]
 * Good, because [argument b]
 * Bad, because [argument c]
-* ... <!-- numbers of pros and cons can vary -->
+* … <!-- numbers of pros and cons can vary -->
+
+## Links <!-- optional -->
+
+* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->
+* … <!-- numbers of links can vary -->

tests/create-first-record-madr.expected

@@ -5,53 +5,71 @@ docs/0002-the-first-decision.md
 cat docs/0002-the-first-decision.md
 # The First Decision
 
-| Date | Status |
-| -- | -- |
-| 1992-01-12 | Accepted |
+* Status: Accepted
+* Deciders: [list everyone involved in the decision] <!-- optional -->
+* Date: 1992-01-12
 
-User Story: [ticket/issue-number] <!-- optional -->
+Technical Story: [description | ticket/issue URL] <!-- optional -->
 
-[context and problem statement]
-[decision drivers | forces | facing] <!-- optional -->
+## Context and Problem Statement
+
+[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
+
+## Decision Drivers <!-- optional -->
+
+* [driver 1, e.g., a force, facing concern, …]
+* [driver 2, e.g., a force, facing concern, …]
+* … <!-- numbers of drivers can vary -->
 
 ## Considered Options
 
 * [option 1]
 * [option 2]
 * [option 3]
-* ... <!-- numbers of options can vary -->
+* … <!-- numbers of options can vary -->
 
 ## Decision Outcome
 
-Chosen option: [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: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].
 
 Positive Consequences: <!-- optional -->
-  - [e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...]
-  - ...
+* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
+* …
 
 Negative consequences: <!-- optional -->
-  - [e.g., compromising quality attribute, follow-up decisions required, ...]
-  - ...
+* [e.g., compromising quality attribute, follow-up decisions required, …]
+* …
 
 ## Pros and Cons of the Options <!-- optional -->
 
 ### [option 1]
 
+[example | description | pointer to more information | …] <!-- optional -->
+
 * Good, because [argument a]
 * Good, because [argument b]
 * Bad, because [argument c]
-* ... <!-- numbers of pros and cons can vary -->
+* … <!-- numbers of pros and cons can vary -->
 
 ### [option 2]
 
+[example | description | pointer to more information | …] <!-- optional -->
+
 * Good, because [argument a]
 * Good, because [argument b]
 * Bad, because [argument c]
-* ... <!-- numbers of pros and cons can vary -->
+* … <!-- numbers of pros and cons can vary -->
 
 ### [option 3]
 
+[example | description | pointer to more information | …] <!-- optional -->
+
 * Good, because [argument a]
 * Good, because [argument b]
 * Bad, because [argument c]
-* ... <!-- numbers of pros and cons can vary -->
+* … <!-- numbers of pros and cons can vary -->
+
+## Links <!-- optional -->
+
+* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->
+* … <!-- numbers of links can vary -->

tests/create-multiple-records-madr.expected

@@ -14,18 +14,18 @@ ls docs
 head -8 docs/0003-second-decision.md
 # Second Decision
 
-| Date | Status |
-| -- | -- |
-| 1992-01-12 | Accepted |
+* Status: Accepted
+* Deciders: [list everyone involved in the decision] <!-- optional -->
+* Date: 1992-01-12
 
-User Story: [ticket/issue-number] <!-- optional -->
+Technical Story: [description | ticket/issue URL] <!-- optional -->
 
 head -8 docs/0004-third-decision.md
 # Third Decision
 
-| Date | Status |
-| -- | -- |
-| 1992-01-12 | Accepted |
+* Status: Accepted
+* Deciders: [list everyone involved in the decision] <!-- optional -->
+* Date: 1992-01-12
 
-User Story: [ticket/issue-number] <!-- optional -->
+Technical Story: [description | ticket/issue URL] <!-- optional -->
 

tests/init-repository-madr.expected

@@ -5,28 +5,26 @@ ls docs
 cat docs/0001-record-architecture-decisions.md
 # Use Markdown Architectural Decision Records
 
-| Date | Status |
-| -- | -- |
-| 1992-01-12 | Accepted |
+## Context and Problem Statement
 
-Should we record the architectural decisions made in this project?
-And if we do, how to structure these recordings?
+We want to record architectural decisions made in this project.
+Which format and structure should these records follow?
 
-## Considered Alternatives
+## Considered Options
 
-* [MADR](https://adr.github.io/madr/) - Markdown Architectural Decision Records
-* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) - The first incarnation of the term "ADR". Maintainable by [adr-tools](https://github.com/npryce/adr-tools).
+* [MADR](https://adr.github.io/madr/) 2.0.3 - The Markdown Architectural Decision Records
+* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) - The first incarnation of the term "ADR"
 * [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) - The Y-Statements
-* [DecisionRecord](https://github.com/schubmat/DecisionCapture) - Agile records by [@schubmat](https://github.com/schubmat/)
 * Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
-* No records
+* Formless - No conventions for file format and structure
 
 ## Decision Outcome
 
-* Chosen Alternative: MADR
+Chosen option: "MADR 2.0.3", 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).
-* The MADR template is lean and fits our development style.
-
-<!-- Pros and cons of alternatives straight-forward to elicit and therefore not captured. -->
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.
+* Version 2.0.3 is the latest one available when starting to document ADRs.