way_of_working-decision_record-madr 1.0.0 → 1.0.1

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 (9) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +10 -1
  3. data/README.md +5 -5
  4. data/code_safety.yml +7 -7
  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/templates/docs/way_of_working/decision-records.md +164 -27
  8. data/lib/way_of_working/decision_record/madr/version.rb +1 -1
  9. metadata +2 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b16cc11fc18e623ef98b696c96d8fa14c3042569ab1352302102257fa83dd280
4
- data.tar.gz: 61324c4b6fe3bd9438d65f7c909ca5caba542617e473100dfac2b38c3fe7fa8e
3
+ metadata.gz: e79bb5980ecce0343b76e3c524a07d3c7e7ab91499bd460cabecda0dad4efaad
4
+ data.tar.gz: 43d4193fdd99641040624024a283e8b676a0a2958b96875b5b5649d49be1328a
5
5
  SHA512:
6
- metadata.gz: 18f57fb43d2c82dc8b8ffdc85693c3dc19057ffccd811c7eebdf563c2e89468415f1ec6d7e2f71d2f68cab0d964ee8c64a8e376074ee09b1a1562a1f8513901b
7
- data.tar.gz: 318f9f13c4b6416bbcddfda456aa798e9d335cb095190d9549100e2c86c66586dd42fcc371be2dfdf4b88620b58f4e460bceb992b8c57235214491662b41e558
6
+ metadata.gz: 8c5722b561b445c348ed062ec4650f839b152ba3d24d41fe6e8c8aa9f585952bf9d98893359309557c454cdae1b776e08ce2a4590c2493c5fb42c046b88a0d16
7
+ data.tar.gz: 5c088b26445e7f47383f76a4035d2a1abf957a059159da94b75dbd3de0787d5c16e2c3798ad7f12c81fd5656e8a0e677bcf02209d2c73e5be47163bdb63cc42b
data/CHANGELOG.md CHANGED
@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.0.1] - 2025-10-16
11
+
12
+ ### Fixed
13
+
14
+ - Fixed the README installation instructions and added the badge for the published gem
15
+ - Fixed the GithubAuditRule to detect stale documentation
16
+ - Made the documentation more token-efficient
17
+
10
18
  ## [1.0.0] - 2025-01-23
11
19
 
12
20
  ### Added
@@ -15,5 +23,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
15
23
  - Added Markdown Any Decision Records (MADR) with generator commands
16
24
  - Added a GitHub audit rule to check for the decision record template
17
25
 
18
- [Unreleased]: https://github.com/HealthDataInsight/way_of_working-decision_record-madr/compare/v1.0.0...HEAD
26
+ [Unreleased]: https://github.com/HealthDataInsight/way_of_working-decision_record-madr/compare/v1.0.1...HEAD
27
+ [1.0.1]: https://github.com/HealthDataInsight/way_of_working-decision_record-madr/compare/v1.0.0...v1.0.1
19
28
  [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: 2173ebacce12376a5d67eb1c4d372f764b118266
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: 2173ebacce12376a5d67eb1c4d372f764b118266
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,7 +83,7 @@ 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
89
  reviewed_by: shilpigoeldev
@@ -99,7 +99,7 @@ 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
@@ -131,11 +131,11 @@ 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: 2173ebacce12376a5d67eb1c4d372f764b118266
139
139
  test/test_helper.rb:
140
140
  comments:
141
141
  reviewed_by: timgentry
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/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.1'
7
7
  end
8
8
  end
9
9
  end
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.1
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-10-16 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: way_of_working