way_of_working-decision_record-madr 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +17 -1
  3. data/README.md +5 -5
  4. data/code_safety.yml +13 -13
  5. data/docs/way_of_working/decision-records.md +164 -27
  6. data/lib/way_of_working/decision_record/madr/github_audit_rule.rb +6 -0
  7. data/lib/way_of_working/decision_record/madr/plugin.rb +12 -0
  8. data/lib/way_of_working/decision_record/madr/templates/docs/way_of_working/decision-records.md +164 -27
  9. data/lib/way_of_working/decision_record/madr/version.rb +1 -1
  10. data/lib/way_of_working/decision_record/madr.rb +0 -1
  11. metadata +3 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b16cc11fc18e623ef98b696c96d8fa14c3042569ab1352302102257fa83dd280
4
- data.tar.gz: 61324c4b6fe3bd9438d65f7c909ca5caba542617e473100dfac2b38c3fe7fa8e
3
+ metadata.gz: e062300a4955579583f43aa3b127b2e0def1635730f61e9ceffc1f489fbe0286
4
+ data.tar.gz: b5c0f273069b46d4e2b933da504626655937804e93a86cdbbd31feea42e43155
5
5
  SHA512:
6
- metadata.gz: 18f57fb43d2c82dc8b8ffdc85693c3dc19057ffccd811c7eebdf563c2e89468415f1ec6d7e2f71d2f68cab0d964ee8c64a8e376074ee09b1a1562a1f8513901b
7
- data.tar.gz: 318f9f13c4b6416bbcddfda456aa798e9d335cb095190d9549100e2c86c66586dd42fcc371be2dfdf4b88620b58f4e460bceb992b8c57235214491662b41e558
6
+ metadata.gz: 57abb2b707129f2e0e4acdf4f830a9dc1eaa08ed1ee655ba5fd03a53bcb0e4e2fef11510c8577519d14d6e46f501570f0e3d028e30c5f7603f754660c5137586
7
+ data.tar.gz: a75a3399d0c607de388a98ce819e40a519f819d8404af6dcfc9c31831027d6f266220df8a0758025313c2717a70b22eec982261a6eaf8b01b87de93556827df3
data/CHANGELOG.md CHANGED
@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.0.2] - 2025-11-24
11
+
12
+ ### Changed
13
+
14
+ - Updated GitHub rule signatures
15
+ - Removed Zeitwerk ignore to make it happier
16
+
17
+ ## [1.0.1] - 2025-10-16
18
+
19
+ ### Fixed
20
+
21
+ - Fixed the README installation instructions and added the badge for the published gem
22
+ - Fixed the GithubAuditRule to detect stale documentation
23
+ - Made the documentation more token-efficient
24
+
10
25
  ## [1.0.0] - 2025-01-23
11
26
 
12
27
  ### Added
@@ -15,5 +30,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
15
30
  - Added Markdown Any Decision Records (MADR) with generator commands
16
31
  - Added a GitHub audit rule to check for the decision record template
17
32
 
18
- [Unreleased]: https://github.com/HealthDataInsight/way_of_working-decision_record-madr/compare/v1.0.0...HEAD
33
+ [Unreleased]: https://github.com/HealthDataInsight/way_of_working-decision_record-madr/compare/v1.0.1...HEAD
34
+ [1.0.1]: https://github.com/HealthDataInsight/way_of_working-decision_record-madr/compare/v1.0.0...v1.0.1
19
35
  [1.0.0]: https://github.com/HealthDataInsight/way_of_working-decision_record-madr/releases/tag/v1.0.0
data/README.md CHANGED
@@ -5,24 +5,24 @@
5
5
  <!-- Way of Working: Additional Badge Holder Start -->
6
6
  <!-- Way of Working: Badge Holder End -->
7
7
 
8
+ [![Gem Version](https://badge.fury.io/rb/way_of_working-decision_record-madr.svg)](https://badge.fury.io/rb/way_of_working-decision_record-madr)
9
+
8
10
  This is a plugin for the [Way of Working](https://github.com/HealthDataInsight/way_of_working) framework. It uses [Markdown Any Decision Records (MADR)](https://adr.github.io/madr/) version 3.0.0 to capture key technical (e.g archtectural) and non-technical decisions within your repository.
9
11
 
10
- You can read about the general approach to capturing decisions on the [GDS Way page on Architecture Decisions](https://gds-way.cloudapps.digital/standards/architecture-decisions.html) and specifics about MADR are available at <https://adr.github.io/madr/>.
12
+ You can read about the general approach to capturing decisions on the [GDS Way page on Architecture Decisions](https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html#documenting-architecture-decisions) and specifics about MADR are available at <https://adr.github.io/madr/>.
11
13
 
12
14
  ## Installation
13
15
 
14
- TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
15
-
16
16
  Install the gem and add to the application's Gemfile by executing:
17
17
 
18
18
  ```bash
19
- bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
19
+ bundle add way_of_working-decision_record-madr
20
20
  ```
21
21
 
22
22
  If bundler is not being used to manage dependencies, install the gem by executing:
23
23
 
24
24
  ```bash
25
- gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
25
+ gem install way_of_working-decision_record-madr
26
26
  ```
27
27
 
28
28
  ## Usage
data/code_safety.yml CHANGED
@@ -35,7 +35,7 @@ file safety:
35
35
  CHANGELOG.md:
36
36
  comments:
37
37
  reviewed_by: shilpigoeldev
38
- safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
38
+ safe_revision: e61aa67a27586671f3ecebb87255ae28d8b56c83
39
39
  Gemfile:
40
40
  comments:
41
41
  reviewed_by: shilpigoeldev
@@ -43,7 +43,7 @@ file safety:
43
43
  Gemfile.lock:
44
44
  comments:
45
45
  reviewed_by: shilpigoeldev
46
- safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
46
+ safe_revision: e61aa67a27586671f3ecebb87255ae28d8b56c83
47
47
  LICENSE.txt:
48
48
  comments:
49
49
  reviewed_by: timgentry
@@ -51,7 +51,7 @@ file safety:
51
51
  README.md:
52
52
  comments:
53
53
  reviewed_by: shilpigoeldev
54
- safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
54
+ safe_revision: 660041678012e6ff1924af769934ff97819c20d7
55
55
  Rakefile:
56
56
  comments:
57
57
  reviewed_by: timgentry
@@ -83,11 +83,11 @@ file safety:
83
83
  docs/way_of_working/decision-records.md:
84
84
  comments:
85
85
  reviewed_by: shilpigoeldev
86
- safe_revision: 463ce4fadf906117b48bb3f9488985ecba1cf6d9
86
+ safe_revision: 660041678012e6ff1924af769934ff97819c20d7
87
87
  lib/way_of_working/decision_record/madr.rb:
88
88
  comments:
89
- reviewed_by: shilpigoeldev
90
- safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
89
+ reviewed_by: timgentry
90
+ safe_revision: 289479ef123d8ca221add2ad1d79c98cc07dd3ab
91
91
  lib/way_of_working/decision_record/madr/generators/init.rb:
92
92
  comments:
93
93
  reviewed_by: shilpigoeldev
@@ -99,15 +99,15 @@ file safety:
99
99
  lib/way_of_working/decision_record/madr/github_audit_rule.rb:
100
100
  comments:
101
101
  reviewed_by: shilpigoeldev
102
- safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
102
+ safe_revision: 2173ebacce12376a5d67eb1c4d372f764b118266
103
103
  lib/way_of_working/decision_record/madr/paths.rb:
104
104
  comments:
105
105
  reviewed_by: shilpigoeldev
106
106
  safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
107
107
  lib/way_of_working/decision_record/madr/plugin.rb:
108
108
  comments:
109
- reviewed_by: shilpigoeldev
110
- safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
109
+ reviewed_by: timgentry
110
+ safe_revision: 289479ef123d8ca221add2ad1d79c98cc07dd3ab
111
111
  lib/way_of_working/decision_record/madr/templates/.github/ISSUE_TEMPLATE/decision-record.md:
112
112
  comments:
113
113
  reviewed_by: shilpigoeldev
@@ -131,19 +131,19 @@ file safety:
131
131
  lib/way_of_working/decision_record/madr/templates/docs/way_of_working/decision-records.md:
132
132
  comments:
133
133
  reviewed_by: shilpigoeldev
134
- safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
134
+ safe_revision: 660041678012e6ff1924af769934ff97819c20d7
135
135
  lib/way_of_working/decision_record/madr/version.rb:
136
136
  comments:
137
137
  reviewed_by: shilpigoeldev
138
- safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
138
+ safe_revision: e61aa67a27586671f3ecebb87255ae28d8b56c83
139
139
  test/test_helper.rb:
140
140
  comments:
141
141
  reviewed_by: timgentry
142
142
  safe_revision: a73811b079389f4706d7f4dbe37ca461b2424642
143
143
  test/way_of_working/audit_github_stub_classes.rb:
144
144
  comments:
145
- reviewed_by: shilpigoeldev
146
- safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
145
+ reviewed_by: timgentry
146
+ safe_revision: 2df79f793e38ddcd81d579c078399b9bb1e7ad52
147
147
  test/way_of_working/decision_record/madr/generators/init_test.rb:
148
148
  comments:
149
149
  reviewed_by: shilpigoeldev
data/docs/way_of_working/decision-records.md CHANGED
@@ -1,58 +1,195 @@
1
1
  ---
2
2
  layout: page
3
+ status: REQUIRED
4
+ enforcement: manual
3
5
  ---
4
6
  # Decision Records
5
7
 
6
- We use [Markdown Any Decision Records (MADR)](https://adr.github.io/madr/) version 3.0.0.
8
+ ## Purpose
7
9
 
8
- In general, projects will follow the [Way of Working](https://github.com/HealthDataInsight/way_of_working) and so decisions captured within individual projects will generally cover decisions that:
10
+ We use [Markdown Any Decision Records (MADR)][madr] v3.0.0 to capture project decisions that:
9
11
 
10
- - are not already covered in the Way of Working
11
- - are covered in the Way of Working, but have specific implementation details which need to be captured
12
- - diverge from the guidance in the Way of Working
12
+ - aren't covered in the [Way of Working][wow]
13
+ - need project-specific implementation details
14
+ - diverge from Way of Working guidance
13
15
 
14
- You can read about the general approach to capturing decisions on the [GDS Way page on Architecture Decisions](https://gds-way.cloudapps.digital/standards/architecture-decisions.html) and specifics about MADR are available at <https://adr.github.io/madr/>.
16
+ {: .note }
17
+ Proposing and reviewing decisions requires familiarity with [GitHub pull requests][gh-pr].
15
18
 
16
- Proposing and reviewing decisions requires an understanding of GitHub and [pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
19
+ ## Scope
17
20
 
18
- ## Usage
21
+ Applies to decisions about:
22
+
23
+ - **Architecture**: System design, technology stack, frameworks
24
+ - **Process**: Development workflows, deployment, testing
25
+ - **Code standards**: Patterns, conventions, library usage
26
+ - **Dependencies**: Adding/removing major libraries or services
27
+ - **Data**: Schema changes, migration strategies
28
+
29
+ **Create ADR when:**
30
+
31
+ - Impact spans multiple components or teams
32
+ - Long-term consequences or significant cost/risk
33
+ - Multiple viable alternatives exist
34
+
35
+ **Don't create ADR for:**
36
+
37
+ - Already covered by Way of Working
38
+ - Tactical implementation details (use code comments)
39
+ - Temporary workarounds or obvious choices
40
+
41
+ ## Requirements
19
42
 
20
- ### Adding Markdown Any Decision Records to your project
43
+ **File naming:** `NNNN-title-with-dashes.md`
21
44
 
22
- To add the MADR v3.0.0 framework to your project, run the following at the command line:
45
+ - `NNNN` = consecutive four-digit number (0001, 0002, etc.)
46
+ - Lowercase title with dashes
47
+ - Located in `docs/decisions/`
48
+
49
+ **Required content:**
50
+
51
+ 1. Status (proposed, accepted, rejected, deprecated, superseded)
52
+ 2. Context and problem statement
53
+ 3. Considered options (minimum 2)
54
+ 4. Decision outcome with justification
55
+ 5. Positive and negative consequences
56
+
57
+ **Status lifecycle:**
58
+
59
+ - **proposed** - Under discussion
60
+ - **accepted** - Approved for implementation
61
+ - **rejected** - Decided against
62
+ - **deprecated** - No longer relevant
63
+ - **superseded** - Replaced by newer ADR (link required)
64
+
65
+ ## Setup
23
66
 
24
67
  ```bash
25
68
  way_of_working init decision_record
26
69
  ```
27
70
 
71
+ ## Usage
72
+
28
73
  ### Create a new decision record
29
74
 
30
- #### Manual approach
75
+ ```bash
76
+ way_of_working new decision_record "Use Markdown Any Decision Records"
77
+ ```
78
+
79
+ **Propose decision:**
31
80
 
32
- 1. Copy `docs/decisions/adr-template.md` to `docs/decisions/NNNN-title-with-dashes.md`, where `NNNN` indicates the next number in sequence.
33
- 2. Edit `NNNN-title-with-dashes.md`.
81
+ 1. Create ADR with status "proposed"
82
+ 2. Open PR, tag stakeholders
83
+ 3. Discuss in PR comments
84
+ 4. Update to "accepted" once consensus reached
85
+ 5. Merge PR
34
86
 
35
- Note you can also use [other patterns for the directory format](https://github.com/joelparkerhenderson/architecture_decision_record#adr-file-name-conventions).
36
- As a consequence, some existing tooling might not be applicable.
87
+ **Supersede existing ADR:**
37
88
 
38
- The filenames are following the pattern `NNNN-title-with-dashes.md`, where
89
+ 1. Create new ADR
90
+ 2. Update old ADR status to "superseded by [0XXX-new-title.md](0XXX-new-title.md)"
91
+ 3. Explain what changed in new ADR
39
92
 
40
- - `NNNN` is a consecutive number and we assume that there won't be more than 9,999 ADRs in one repository.
41
- - the title is stored using dashes and lowercase, because [adr-tools] also does that.
42
- - the suffix is `.md`, because it is a [Markdown](https://github.github.com/gfm/) file.
93
+ ## Enforcement
43
94
 
44
- Decisions are placed in the subfolder `decisions/` to keep them close to the documentation but also separate the decisions from other documentation.
95
+ **PR Review:**
45
96
 
46
- #### Automatic approach
97
+ - All ADRs submitted via PR
98
+ - Maintainer approval required
99
+ - Verify MADR template structure, file naming, location
100
+ - Check minimum 2 options with justification
47
101
 
48
- To create a new decision record, run:
102
+ **Quality checklist:**
49
103
 
50
- ```bash
51
- way_of_working new decision_record [NAME]
104
+ - ✅ Multiple alternatives with pros/cons
105
+ - ✅ Clear context and constraints
106
+ - ✅ Explicit trade-offs
107
+ - ❌ Only one option presented
108
+ - ❌ Missing justification or context
109
+
110
+ **Maintenance:**
111
+
112
+ - Quarterly review for relevance
113
+ - Update deprecated/superseded status as needed
114
+
115
+ ## Examples
116
+
117
+ **Database choice:**
118
+
119
+ ```markdown
120
+ # Use PostgreSQL for Primary Database
121
+
122
+ **Status:** accepted
123
+ **Date:** 2025-10-15
124
+
125
+ ## Context and Problem Statement
126
+
127
+ Need relational database for user data with complex relationships.
128
+ Constraints: ACID compliance, 100K users/1M records, prefer open-source.
129
+
130
+ ## Considered Options
131
+
132
+ 1. PostgreSQL (self-hosted)
133
+ 2. MySQL
134
+ 3. RDS PostgreSQL
135
+
136
+ ## Decision Outcome
137
+
138
+ **Chosen:** PostgreSQL (self-hosted)
139
+
140
+ **Pros:** Open-source, advanced features (JSON, full-text search), ACID, team experience
141
+ **Cons:** DevOps overhead, manual backup, manual scaling
142
+
143
+ **Why:** Meets requirements within budget. Cloud-managed exceeds budget by 40%.
144
+ Team expertise mitigates complexity.
145
+
146
+ **Alternatives rejected:**
147
+ - MySQL: No advantage over PostgreSQL
148
+ - RDS: Cost $200-500/month exceeds budget
52
149
  ```
53
150
 
54
- Where `[NAME]` is the title of your decision record, for example:
151
+ **Superseded ADR:**
55
152
 
56
- ```bash
57
- way_of_working new decision_record "Use Markdown Any Decision Records"
153
+ ```markdown
154
+ # Use Jest for Frontend Testing
155
+
156
+ **Status:** superseded by [0015-use-vitest.md](0015-use-vitest.md)
157
+ **Date:** 2025-01-10 (original), 2025-09-15 (superseded)
158
+
159
+ **Why superseded:** Vitest now standard for Vite projects,
160
+ better integration and performance.
161
+ ```
162
+
163
+ **Rejected decision:**
164
+
165
+ ```markdown
166
+ # Use GraphQL for API Layer
167
+
168
+ **Status:** rejected
169
+ **Date:** 2025-03-20
170
+
171
+ ## Decision Outcome
172
+
173
+ **Chosen:** Continue with REST API
174
+
175
+ **Why rejected:**
176
+ - Current REST meets all requirements
177
+ - Team lacks GraphQL expertise (4-6 week learning curve)
178
+ - Migration cost: 8 engineer-weeks
179
+ - No client needs GraphQL features
180
+
181
+ **Reconsider when:** Multiple clients need flexible fetching
182
+ or over-fetching impacts performance.
58
183
  ```
184
+
185
+ ## Resources
186
+
187
+ - [MADR Documentation][madr]
188
+ - [GDS Architecture Decisions][gds-way]
189
+ - [Way of Working CLI][wow-cli]
190
+
191
+ [madr]: https://adr.github.io/madr/
192
+ [wow]: https://github.com/HealthDataInsight/way_of_working
193
+ [gds-way]: https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html
194
+ [gh-pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
195
+ [wow-cli]: ../cli.md
data/lib/way_of_working/decision_record/madr/github_audit_rule.rb CHANGED
@@ -10,6 +10,7 @@ module WayOfWorking
10
10
  class GithubAuditRule < ::WayOfWorking::Audit::Github::Rules::Base
11
11
  ADR_TEMPLATE_PATH = 'docs/decisions/adr-template.md'
12
12
  DECISION_ZERO_PATH = 'docs/decisions/0000-use-markdown-any-decision-records.md'
13
+ WOW_DOCUMENTATION_PATH = 'docs/way_of_working/decision-records.md'
13
14
 
14
15
  source_root ::WayOfWorking::DecisionRecord::Madr.source_root
15
16
 
@@ -17,6 +18,11 @@ module WayOfWorking
17
18
  @errors << 'No MADR Decision Record template found' unless repo_file_contains?(
18
19
  ADR_TEMPLATE_PATH, '## Context and Problem Statement'
19
20
  )
21
+
22
+ unless repo_file_contains_source_file?(WOW_DOCUMENTATION_PATH)
23
+ @errors << 'Stale or missing documentation for using MADR Decision Records'
24
+ end
25
+
20
26
  return if repo_file_contains_source_file?(DECISION_ZERO_PATH)
21
27
 
22
28
  @errors << 'No 0000-use-markdown-any-decision-records.md Decision Record found'
data/lib/way_of_working/decision_record/madr/plugin.rb CHANGED
@@ -1 +1,13 @@
1
1
  require 'way_of_working/decision_record/madr'
2
+
3
+ # Add any plug specific code here
4
+
5
+ module WayOfWorking
6
+ module DecisionRecord
7
+ module Madr
8
+ # This makes zeitwerk happy, which makes us happy too
9
+ module Plugin
10
+ end
11
+ end
12
+ end
13
+ end
data/lib/way_of_working/decision_record/madr/templates/docs/way_of_working/decision-records.md CHANGED
@@ -1,58 +1,195 @@
1
1
  ---
2
2
  layout: page
3
+ status: REQUIRED
4
+ enforcement: manual
3
5
  ---
4
6
  # Decision Records
5
7
 
6
- We use [Markdown Any Decision Records (MADR)](https://adr.github.io/madr/) version 3.0.0.
8
+ ## Purpose
7
9
 
8
- In general, projects will follow the [Way of Working](https://github.com/HealthDataInsight/way_of_working) and so decisions captured within individual projects will generally cover decisions that:
10
+ We use [Markdown Any Decision Records (MADR)][madr] v3.0.0 to capture project decisions that:
9
11
 
10
- - are not already covered in the Way of Working
11
- - are covered in the Way of Working, but have specific implementation details which need to be captured
12
- - diverge from the guidance in the Way of Working
12
+ - aren't covered in the [Way of Working][wow]
13
+ - need project-specific implementation details
14
+ - diverge from Way of Working guidance
13
15
 
14
- You can read about the general approach to capturing decisions on the [GDS Way page on Architecture Decisions](https://gds-way.cloudapps.digital/standards/architecture-decisions.html) and specifics about MADR are available at <https://adr.github.io/madr/>.
16
+ {: .note }
17
+ Proposing and reviewing decisions requires familiarity with [GitHub pull requests][gh-pr].
15
18
 
16
- Proposing and reviewing decisions requires an understanding of GitHub and [pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
19
+ ## Scope
17
20
 
18
- ## Usage
21
+ Applies to decisions about:
22
+
23
+ - **Architecture**: System design, technology stack, frameworks
24
+ - **Process**: Development workflows, deployment, testing
25
+ - **Code standards**: Patterns, conventions, library usage
26
+ - **Dependencies**: Adding/removing major libraries or services
27
+ - **Data**: Schema changes, migration strategies
28
+
29
+ **Create ADR when:**
30
+
31
+ - Impact spans multiple components or teams
32
+ - Long-term consequences or significant cost/risk
33
+ - Multiple viable alternatives exist
34
+
35
+ **Don't create ADR for:**
36
+
37
+ - Already covered by Way of Working
38
+ - Tactical implementation details (use code comments)
39
+ - Temporary workarounds or obvious choices
40
+
41
+ ## Requirements
19
42
 
20
- ### Adding Markdown Any Decision Records to your project
43
+ **File naming:** `NNNN-title-with-dashes.md`
21
44
 
22
- To add the MADR v3.0.0 framework to your project, run the following at the command line:
45
+ - `NNNN` = consecutive four-digit number (0001, 0002, etc.)
46
+ - Lowercase title with dashes
47
+ - Located in `docs/decisions/`
48
+
49
+ **Required content:**
50
+
51
+ 1. Status (proposed, accepted, rejected, deprecated, superseded)
52
+ 2. Context and problem statement
53
+ 3. Considered options (minimum 2)
54
+ 4. Decision outcome with justification
55
+ 5. Positive and negative consequences
56
+
57
+ **Status lifecycle:**
58
+
59
+ - **proposed** - Under discussion
60
+ - **accepted** - Approved for implementation
61
+ - **rejected** - Decided against
62
+ - **deprecated** - No longer relevant
63
+ - **superseded** - Replaced by newer ADR (link required)
64
+
65
+ ## Setup
23
66
 
24
67
  ```bash
25
68
  way_of_working init decision_record
26
69
  ```
27
70
 
71
+ ## Usage
72
+
28
73
  ### Create a new decision record
29
74
 
30
- #### Manual approach
75
+ ```bash
76
+ way_of_working new decision_record "Use Markdown Any Decision Records"
77
+ ```
78
+
79
+ **Propose decision:**
31
80
 
32
- 1. Copy `docs/decisions/adr-template.md` to `docs/decisions/NNNN-title-with-dashes.md`, where `NNNN` indicates the next number in sequence.
33
- 2. Edit `NNNN-title-with-dashes.md`.
81
+ 1. Create ADR with status "proposed"
82
+ 2. Open PR, tag stakeholders
83
+ 3. Discuss in PR comments
84
+ 4. Update to "accepted" once consensus reached
85
+ 5. Merge PR
34
86
 
35
- Note you can also use [other patterns for the directory format](https://github.com/joelparkerhenderson/architecture_decision_record#adr-file-name-conventions).
36
- As a consequence, some existing tooling might not be applicable.
87
+ **Supersede existing ADR:**
37
88
 
38
- The filenames are following the pattern `NNNN-title-with-dashes.md`, where
89
+ 1. Create new ADR
90
+ 2. Update old ADR status to "superseded by [0XXX-new-title.md](0XXX-new-title.md)"
91
+ 3. Explain what changed in new ADR
39
92
 
40
- - `NNNN` is a consecutive number and we assume that there won't be more than 9,999 ADRs in one repository.
41
- - the title is stored using dashes and lowercase, because [adr-tools] also does that.
42
- - the suffix is `.md`, because it is a [Markdown](https://github.github.com/gfm/) file.
93
+ ## Enforcement
43
94
 
44
- Decisions are placed in the subfolder `decisions/` to keep them close to the documentation but also separate the decisions from other documentation.
95
+ **PR Review:**
45
96
 
46
- #### Automatic approach
97
+ - All ADRs submitted via PR
98
+ - Maintainer approval required
99
+ - Verify MADR template structure, file naming, location
100
+ - Check minimum 2 options with justification
47
101
 
48
- To create a new decision record, run:
102
+ **Quality checklist:**
49
103
 
50
- ```bash
51
- way_of_working new decision_record [NAME]
104
+ - ✅ Multiple alternatives with pros/cons
105
+ - ✅ Clear context and constraints
106
+ - ✅ Explicit trade-offs
107
+ - ❌ Only one option presented
108
+ - ❌ Missing justification or context
109
+
110
+ **Maintenance:**
111
+
112
+ - Quarterly review for relevance
113
+ - Update deprecated/superseded status as needed
114
+
115
+ ## Examples
116
+
117
+ **Database choice:**
118
+
119
+ ```markdown
120
+ # Use PostgreSQL for Primary Database
121
+
122
+ **Status:** accepted
123
+ **Date:** 2025-10-15
124
+
125
+ ## Context and Problem Statement
126
+
127
+ Need relational database for user data with complex relationships.
128
+ Constraints: ACID compliance, 100K users/1M records, prefer open-source.
129
+
130
+ ## Considered Options
131
+
132
+ 1. PostgreSQL (self-hosted)
133
+ 2. MySQL
134
+ 3. RDS PostgreSQL
135
+
136
+ ## Decision Outcome
137
+
138
+ **Chosen:** PostgreSQL (self-hosted)
139
+
140
+ **Pros:** Open-source, advanced features (JSON, full-text search), ACID, team experience
141
+ **Cons:** DevOps overhead, manual backup, manual scaling
142
+
143
+ **Why:** Meets requirements within budget. Cloud-managed exceeds budget by 40%.
144
+ Team expertise mitigates complexity.
145
+
146
+ **Alternatives rejected:**
147
+ - MySQL: No advantage over PostgreSQL
148
+ - RDS: Cost $200-500/month exceeds budget
52
149
  ```
53
150
 
54
- Where `[NAME]` is the title of your decision record, for example:
151
+ **Superseded ADR:**
55
152
 
56
- ```bash
57
- way_of_working new decision_record "Use Markdown Any Decision Records"
153
+ ```markdown
154
+ # Use Jest for Frontend Testing
155
+
156
+ **Status:** superseded by [0015-use-vitest.md](0015-use-vitest.md)
157
+ **Date:** 2025-01-10 (original), 2025-09-15 (superseded)
158
+
159
+ **Why superseded:** Vitest now standard for Vite projects,
160
+ better integration and performance.
161
+ ```
162
+
163
+ **Rejected decision:**
164
+
165
+ ```markdown
166
+ # Use GraphQL for API Layer
167
+
168
+ **Status:** rejected
169
+ **Date:** 2025-03-20
170
+
171
+ ## Decision Outcome
172
+
173
+ **Chosen:** Continue with REST API
174
+
175
+ **Why rejected:**
176
+ - Current REST meets all requirements
177
+ - Team lacks GraphQL expertise (4-6 week learning curve)
178
+ - Migration cost: 8 engineer-weeks
179
+ - No client needs GraphQL features
180
+
181
+ **Reconsider when:** Multiple clients need flexible fetching
182
+ or over-fetching impacts performance.
58
183
  ```
184
+
185
+ ## Resources
186
+
187
+ - [MADR Documentation][madr]
188
+ - [GDS Architecture Decisions][gds-way]
189
+ - [Way of Working CLI][wow-cli]
190
+
191
+ [madr]: https://adr.github.io/madr/
192
+ [wow]: https://github.com/HealthDataInsight/way_of_working
193
+ [gds-way]: https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html
194
+ [gh-pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
195
+ [wow-cli]: ../cli.md
data/lib/way_of_working/decision_record/madr/version.rb CHANGED
@@ -3,7 +3,7 @@
3
3
  module WayOfWorking
4
4
  module DecisionRecord
5
5
  module Madr
6
- VERSION = '1.0.0'
6
+ VERSION = '1.0.2'
7
7
  end
8
8
  end
9
9
  end
data/lib/way_of_working/decision_record/madr.rb CHANGED
@@ -12,7 +12,6 @@ rescue LoadError # rubocop:disable Lint/SuppressedException
12
12
  end
13
13
 
14
14
  loader = Zeitwerk::Loader.for_gem_extension(WayOfWorking::DecisionRecord)
15
- loader.ignore("#{__dir__}/madr/plugin.rb")
16
15
  loader.setup
17
16
 
18
17
  module WayOfWorking
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: way_of_working-decision_record-madr
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.0.0
4
+ version: 1.0.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tim Gentry
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2025-01-23 00:00:00.000000000 Z
11
+ date: 2025-11-24 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: way_of_working
@@ -94,7 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
94
94
  - !ruby/object:Gem::Version
95
95
  version: '0'
96
96
  requirements: []
97
- rubygems_version: 3.5.22
97
+ rubygems_version: 3.3.26
98
98
  signing_key:
99
99
  specification_version: 4
100
100
  summary: Way of Working plugin for Decision Records using MADR v3