way_of_working-decision_record-madr 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (27) hide show
  1. checksums.yaml +7 -0
  2. data/.mega-linter.yml +145 -0
  3. data/.rubocop +1 -0
  4. data/CHANGELOG.md +19 -0
  5. data/LICENSE.txt +21 -0
  6. data/README.md +64 -0
  7. data/Rakefile +16 -0
  8. data/code_safety.yml +170 -0
  9. data/docs/decisions/0000-use-markdown-any-decision-records.md +30 -0
  10. data/docs/decisions/README.md +7 -0
  11. data/docs/decisions/adr-template.md +82 -0
  12. data/docs/decisions/index.md +48 -0
  13. data/docs/way_of_working/decision-records.md +58 -0
  14. data/lib/way_of_working/decision_record/madr/generators/init.rb +41 -0
  15. data/lib/way_of_working/decision_record/madr/generators/new.rb +69 -0
  16. data/lib/way_of_working/decision_record/madr/github_audit_rule.rb +44 -0
  17. data/lib/way_of_working/decision_record/madr/paths.rb +20 -0
  18. data/lib/way_of_working/decision_record/madr/plugin.rb +1 -0
  19. data/lib/way_of_working/decision_record/madr/templates/.github/ISSUE_TEMPLATE/decision-record.md +26 -0
  20. data/lib/way_of_working/decision_record/madr/templates/docs/decisions/0000-use-markdown-any-decision-records.md +30 -0
  21. data/lib/way_of_working/decision_record/madr/templates/docs/decisions/README.md +7 -0
  22. data/lib/way_of_working/decision_record/madr/templates/docs/decisions/adr-template.md.tt +82 -0
  23. data/lib/way_of_working/decision_record/madr/templates/docs/decisions/index.md +48 -0
  24. data/lib/way_of_working/decision_record/madr/templates/docs/way_of_working/decision-records.md +58 -0
  25. data/lib/way_of_working/decision_record/madr/version.rb +9 -0
  26. data/lib/way_of_working/decision_record/madr.rb +58 -0
  27. metadata +101 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: b16cc11fc18e623ef98b696c96d8fa14c3042569ab1352302102257fa83dd280
4
+ data.tar.gz: 61324c4b6fe3bd9438d65f7c909ca5caba542617e473100dfac2b38c3fe7fa8e
5
+ SHA512:
6
+ metadata.gz: 18f57fb43d2c82dc8b8ffdc85693c3dc19057ffccd811c7eebdf563c2e89468415f1ec6d7e2f71d2f68cab0d964ee8c64a8e376074ee09b1a1562a1f8513901b
7
+ data.tar.gz: 318f9f13c4b6416bbcddfda456aa798e9d335cb095190d9549100e2c86c66586dd42fcc371be2dfdf4b88620b58f4e460bceb992b8c57235214491662b41e558
data/.mega-linter.yml ADDED
@@ -0,0 +1,145 @@
1
+ ---
2
+ # Configuration file for MegaLinter
3
+ # See all available variables at https://megalinter.io/configuration/
4
+ # and in linters documentation
5
+
6
+ APPLY_FIXES: none # all, none, or list of linter keys
7
+ ENABLE_LINTERS: # All other linters will be disabled by default
8
+ ### Languages
9
+ - BASH_EXEC # in Super-Linter
10
+ - BASH_SHELLCHECK # in Super-Linter
11
+ - BASH_SHFMT # in Super-Linter
12
+ - C_CLANG_FORMAT
13
+ - C_CPPLINT
14
+ # - CLOJURE_CLJ_KONDO # in Super-Linter
15
+ # - CLOJURE_CLJSTYLE
16
+ - COFFEE_COFFEELINT # in Super-Linter
17
+ - CPP_CLANG_FORMAT
18
+ - CPP_CPPLINT # in Super-Linter
19
+ - CSHARP_CSHARPIER
20
+ - CSHARP_DOTNET_FORMAT # in Super-Linter
21
+ - CSHARP_ROSLYNATOR
22
+ - DART_DARTANALYZER # in Super-Linter
23
+ - GO_GOLANGCI_LINT # in Super-Linter
24
+ - GO_REVIVE
25
+ # - GROOVY_NPM_GROOVY_LINT # in Super-Linter
26
+ - JAVA_CHECKSTYLE # in Super-Linter
27
+ - JAVA_PMD
28
+ - JAVASCRIPT_ES # in Super-Linter
29
+ # - JAVASCRIPT_PRETTIER
30
+ - JAVASCRIPT_STANDARD # in Super-Linter
31
+ - JSX_ESLINT
32
+ - KOTLIN_DETEKT
33
+ - KOTLIN_KTLINT # in Super-Linter
34
+ # - LUA_LUACHECK # in Super-Linter
35
+ # - LUA_SELENE
36
+ # - LUA_STYLUA
37
+ - MAKEFILE_CHECKMAKE
38
+ # - PERL_PERLCRITIC # in Super-Linter
39
+ # - PHP_BUILTIN
40
+ # - PHP_PHPCS # in Super-Linter
41
+ # - PHP_PHPCSFIXER
42
+ # - PHP_PHPLINT # in Super-Linter
43
+ # - PHP_PHPSTAN # in Super-Linter
44
+ # - PHP_PSALM # in Super-Linter
45
+ # - POWERSHELL_POWERSHELL
46
+ # - POWERSHELL_POWERSHELL_FORMATTER
47
+ - PYTHON_BANDIT
48
+ - PYTHON_BLACK # in Super-Linter
49
+ - PYTHON_FLAKE8 # in Super-Linter
50
+ - PYTHON_ISORT # in Super-Linter
51
+ - PYTHON_MYPY
52
+ - PYTHON_PYLINT # in Super-Linter
53
+ - PYTHON_PYRIGHT
54
+ - PYTHON_RUFF
55
+ - R_LINTR # in Super-Linter
56
+ # - RAKU_RAKU # in Super-Linter
57
+ # - RUBY_RUBOCOP # in Super-Linter
58
+ - RUST_CLIPPY # in Super-Linter
59
+ # - SALESFORCE_LIGHTNING_FLOW_SCANNER
60
+ # - SALESFORCE_SFDX_SCANNER_APEX
61
+ # - SALESFORCE_SFDX_SCANNER_AURA
62
+ # - SALESFORCE_SFDX_SCANNER_LWC
63
+ - SCALA_SCALAFIX
64
+ - SQL_SQLFLUFF # in Super-Linter
65
+ - SQL_TSQLLINT
66
+ - SWIFT_SWIFTLINT
67
+ - TSX_ESLINT
68
+ - TYPESCRIPT_ES # in Super-Linter
69
+ # - TYPESCRIPT_PRETTIER
70
+ - TYPESCRIPT_STANDARD # in Super-Linter
71
+ # - VBDOTNET_DOTNET_FORMAT
72
+
73
+ ### Formats
74
+ - CSS_STYLELINT # in Super-Linter
75
+ - ENV_DOTENV_LINTER # in Super-Linter
76
+ # - GRAPHQL_GRAPHQL_SCHEMA_LINTER
77
+ # - HTML_DJLINT # Refuses to see config file
78
+ - HTML_HTMLHINT # in Super-Linter
79
+ - JSON_ESLINT_PLUGIN_JSONC # in Super-Linter
80
+ - JSON_JSONLINT
81
+ - JSON_NPM_PACKAGE_JSON_LINT
82
+ # - JSON_PRETTIER
83
+ - JSON_V8R
84
+ # - LATEX_CHKTEX # in Super-Linter
85
+ - MARKDOWN_MARKDOWNLINT # in Super-Linter
86
+ - MARKDOWN_MARKDOWN_LINK_CHECK
87
+ - MARKDOWN_MARKDOWN_TABLE_FORMATTER
88
+ - MARKDOWN_REMARK_LINT
89
+ # - PROTOBUF_PROTOLINT # in Super-Linter
90
+ # - RST_RSTCHECK
91
+ # - RST_RSTFMT
92
+ # - RST_RST_LINT
93
+ - XML_XMLLINT # in Super-Linter
94
+ # - YAML_PRETTIER
95
+ - YAML_V8R
96
+ - YAML_YAMLLINT # in Super-Linter
97
+
98
+ ### Tooling
99
+ - ACTION_ACTIONLINT # in Super-Linter
100
+ - ANSIBLE_ANSIBLE_LINT # in Super-Linter
101
+ - API_SPECTRAL
102
+ - ARM_ARM_TTK # in Super-Linter
103
+ # - BICEP_BICEP_LINTER
104
+ - CLOUDFORMATION_CFN_LINT # in Super-Linter
105
+ - DOCKERFILE_HADOLINT # in Super-Linter
106
+ - EDITORCONFIG_EDITORCONFIG_CHECKER # in Super-Linter
107
+ # - GHERKIN_GHERKIN_LINT # in Super-Linter
108
+ - KUBERNETES_HELM
109
+ - KUBERNETES_KUBECONFORM
110
+ - KUBERNETES_KUBESCAPE
111
+ - PUPPET_PUPPET_LINT
112
+ # - SNAKEMAKE_LINT # in Super-Linter
113
+ # - SNAKEMAKE_SNAKEFMT # in Super-Linter
114
+ # - TEKTON_TEKTON_LINT # in Super-Linter
115
+ - TERRAFORM_TERRAFORM_FMT # in Super-Linter
116
+ - TERRAFORM_TERRAGRUNT # in Super-Linter
117
+ - TERRAFORM_TERRASCAN # in Super-Linter
118
+ - TERRAFORM_TFLINT # in Super-Linter
119
+
120
+ ### Code quality checkers
121
+ - COPYPASTE_JSCPD # in Super-Linter
122
+ - REPOSITORY_CHECKOV
123
+ - REPOSITORY_DEVSKIM
124
+ - REPOSITORY_DUSTILOCK
125
+ - REPOSITORY_GIT_DIFF
126
+ - REPOSITORY_GITLEAKS # in Super-Linter
127
+ - REPOSITORY_GRYPE
128
+ - REPOSITORY_KICS
129
+ - REPOSITORY_LS_LINT
130
+ - REPOSITORY_SECRETLINT
131
+ - REPOSITORY_SEMGREP
132
+ - REPOSITORY_SYFT
133
+ - REPOSITORY_TRIVY
134
+ - REPOSITORY_TRIVY_SBOM
135
+ - REPOSITORY_TRUFFLEHOG
136
+ # - SPELL_CSPELL
137
+ - SPELL_LYCHEE
138
+ - SPELL_PROSELINT
139
+ - SPELL_VALE
140
+
141
+ SHOW_ELAPSED_TIME: false
142
+ FILEIO_REPORTER: false
143
+ FAIL_IF_MISSING_LINTER_IN_FLAVOR: true
144
+ # DISABLE_ERRORS: true # Uncomment if you want MegaLinter to detect
145
+ # errors but not block CI to pass
data/.rubocop ADDED
@@ -0,0 +1 @@
1
+ --config .github/linters/rubocop_defaults.yml
data/CHANGELOG.md ADDED
@@ -0,0 +1,19 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [1.0.0] - 2025-01-23
11
+
12
+ ### Added
13
+
14
+ - Added a Decision Record issue template
15
+ - Added Markdown Any Decision Records (MADR) with generator commands
16
+ - Added a GitHub audit rule to check for the decision record template
17
+
18
+ [Unreleased]: https://github.com/HealthDataInsight/way_of_working-decision_record-madr/compare/v1.0.0...HEAD
19
+ [1.0.0]: https://github.com/HealthDataInsight/way_of_working-decision_record-madr/releases/tag/v1.0.0
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2024 Health Data Insight CIC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,64 @@
1
+ # WayOfWorking::DecisionRecord::Madr
2
+
3
+ <!-- Way of Working: Main Badge Holder Start -->
4
+ ![Way of Working Badge](https://img.shields.io/badge/Way_of_Working-v2.0.1-%238169e3?labelColor=black)
5
+ <!-- Way of Working: Additional Badge Holder Start -->
6
+ <!-- Way of Working: Badge Holder End -->
7
+
8
+ 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
+
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/>.
11
+
12
+ ## Installation
13
+
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
+ Install the gem and add to the application's Gemfile by executing:
17
+
18
+ ```bash
19
+ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
20
+ ```
21
+
22
+ If bundler is not being used to manage dependencies, install the gem by executing:
23
+
24
+ ```bash
25
+ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
26
+ ```
27
+
28
+ ## Usage
29
+
30
+ To add the [Markdown Any Decision Records (MADR)](https://adr.github.io/madr/) v3.0.0 framework to your project, run the following at the command line:
31
+
32
+ ```bash
33
+ way_of_working init decision_record
34
+ ```
35
+
36
+ To create a new decision record, run:
37
+
38
+ ```bash
39
+ way_of_working new decision_record [NAME]
40
+ ```
41
+
42
+ Where `[NAME]` is the title of your decision record, for example:
43
+
44
+ ```bash
45
+ way_of_working new decision_record "Use Markdown Any Decision Records"
46
+ ```
47
+
48
+ ## Development
49
+
50
+ After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
51
+
52
+ To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
53
+
54
+ ## Contributing
55
+
56
+ Bug reports and pull requests are welcome on GitHub at <https://github.com/HealthDataInsight/way_of_working-decision_record-madr>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/HealthDataInsight/way_of_working-decision_record-madr/blob/main/CODE_OF_CONDUCT.md).
57
+
58
+ ## License
59
+
60
+ The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
61
+
62
+ ## Code of Conduct
63
+
64
+ Everyone interacting in the WayOfWorking::DecisionRecord::Madr project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/HealthDataInsight/way_of_working-decision_record-madr/blob/main/CODE_OF_CONDUCT.md).
data/Rakefile ADDED
@@ -0,0 +1,16 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'bundler/gem_tasks'
4
+ require 'rake/testtask'
5
+ require 'way_of_working/tasks'
6
+
7
+ Rake::TestTask.new(:test) do |t|
8
+ t.libs << 'lib'
9
+ t.libs << 'test'
10
+ t.test_files = FileList['test/**/*_test.rb']
11
+ t.verbose = false
12
+ t.warning = false
13
+ end
14
+
15
+ desc 'Run tests'
16
+ task default: :test
data/code_safety.yml ADDED
@@ -0,0 +1,170 @@
1
+ ---
2
+ file safety:
3
+ ".github/ISSUE_TEMPLATE/decision-record.md":
4
+ comments:
5
+ reviewed_by: shilpigoeldev
6
+ safe_revision: 463ce4fadf906117b48bb3f9488985ecba1cf6d9
7
+ ".github/linters/.markdown-link-check.json":
8
+ comments:
9
+ reviewed_by: timgentry
10
+ safe_revision: a73811b079389f4706d7f4dbe37ca461b2424642
11
+ ".github/linters/rubocop_defaults.yml":
12
+ comments:
13
+ reviewed_by: timgentry
14
+ safe_revision: a73811b079389f4706d7f4dbe37ca461b2424642
15
+ ".github/workflows/main.yml":
16
+ comments:
17
+ reviewed_by: shilpigoeldev
18
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
19
+ ".github/workflows/mega-linter.yml":
20
+ comments:
21
+ reviewed_by: shilpigoeldev
22
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
23
+ ".gitignore":
24
+ comments:
25
+ reviewed_by: shilpigoeldev
26
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
27
+ ".mega-linter.yml":
28
+ comments:
29
+ reviewed_by: shilpigoeldev
30
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
31
+ ".rubocop":
32
+ comments:
33
+ reviewed_by: timgentry
34
+ safe_revision: a73811b079389f4706d7f4dbe37ca461b2424642
35
+ CHANGELOG.md:
36
+ comments:
37
+ reviewed_by: shilpigoeldev
38
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
39
+ Gemfile:
40
+ comments:
41
+ reviewed_by: shilpigoeldev
42
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
43
+ Gemfile.lock:
44
+ comments:
45
+ reviewed_by: shilpigoeldev
46
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
47
+ LICENSE.txt:
48
+ comments:
49
+ reviewed_by: timgentry
50
+ safe_revision: a73811b079389f4706d7f4dbe37ca461b2424642
51
+ README.md:
52
+ comments:
53
+ reviewed_by: shilpigoeldev
54
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
55
+ Rakefile:
56
+ comments:
57
+ reviewed_by: timgentry
58
+ safe_revision: a73811b079389f4706d7f4dbe37ca461b2424642
59
+ bin/console:
60
+ comments:
61
+ reviewed_by: timgentry
62
+ safe_revision: a73811b079389f4706d7f4dbe37ca461b2424642
63
+ bin/setup:
64
+ comments:
65
+ reviewed_by: timgentry
66
+ safe_revision: a73811b079389f4706d7f4dbe37ca461b2424642
67
+ docs/decisions/0000-use-markdown-any-decision-records.md:
68
+ comments:
69
+ reviewed_by: shilpigoeldev
70
+ safe_revision: 463ce4fadf906117b48bb3f9488985ecba1cf6d9
71
+ docs/decisions/README.md:
72
+ comments:
73
+ reviewed_by: shilpigoeldev
74
+ safe_revision: 463ce4fadf906117b48bb3f9488985ecba1cf6d9
75
+ docs/decisions/adr-template.md:
76
+ comments:
77
+ reviewed_by: shilpigoeldev
78
+ safe_revision: 463ce4fadf906117b48bb3f9488985ecba1cf6d9
79
+ docs/decisions/index.md:
80
+ comments:
81
+ reviewed_by: shilpigoeldev
82
+ safe_revision: 463ce4fadf906117b48bb3f9488985ecba1cf6d9
83
+ docs/way_of_working/decision-records.md:
84
+ comments:
85
+ reviewed_by: shilpigoeldev
86
+ safe_revision: 463ce4fadf906117b48bb3f9488985ecba1cf6d9
87
+ lib/way_of_working/decision_record/madr.rb:
88
+ comments:
89
+ reviewed_by: shilpigoeldev
90
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
91
+ lib/way_of_working/decision_record/madr/generators/init.rb:
92
+ comments:
93
+ reviewed_by: shilpigoeldev
94
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
95
+ lib/way_of_working/decision_record/madr/generators/new.rb:
96
+ comments:
97
+ reviewed_by: shilpigoeldev
98
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
99
+ lib/way_of_working/decision_record/madr/github_audit_rule.rb:
100
+ comments:
101
+ reviewed_by: shilpigoeldev
102
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
103
+ lib/way_of_working/decision_record/madr/paths.rb:
104
+ comments:
105
+ reviewed_by: shilpigoeldev
106
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
107
+ lib/way_of_working/decision_record/madr/plugin.rb:
108
+ comments:
109
+ reviewed_by: shilpigoeldev
110
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
111
+ lib/way_of_working/decision_record/madr/templates/.github/ISSUE_TEMPLATE/decision-record.md:
112
+ comments:
113
+ reviewed_by: shilpigoeldev
114
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
115
+ lib/way_of_working/decision_record/madr/templates/docs/decisions/0000-use-markdown-any-decision-records.md:
116
+ comments:
117
+ reviewed_by: shilpigoeldev
118
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
119
+ lib/way_of_working/decision_record/madr/templates/docs/decisions/README.md:
120
+ comments:
121
+ reviewed_by: shilpigoeldev
122
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
123
+ lib/way_of_working/decision_record/madr/templates/docs/decisions/adr-template.md.tt:
124
+ comments:
125
+ reviewed_by: shilpigoeldev
126
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
127
+ lib/way_of_working/decision_record/madr/templates/docs/decisions/index.md:
128
+ comments:
129
+ reviewed_by: shilpigoeldev
130
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
131
+ lib/way_of_working/decision_record/madr/templates/docs/way_of_working/decision-records.md:
132
+ comments:
133
+ reviewed_by: shilpigoeldev
134
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
135
+ lib/way_of_working/decision_record/madr/version.rb:
136
+ comments:
137
+ reviewed_by: shilpigoeldev
138
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
139
+ test/test_helper.rb:
140
+ comments:
141
+ reviewed_by: timgentry
142
+ safe_revision: a73811b079389f4706d7f4dbe37ca461b2424642
143
+ test/way_of_working/audit_github_stub_classes.rb:
144
+ comments:
145
+ reviewed_by: shilpigoeldev
146
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
147
+ test/way_of_working/decision_record/madr/generators/init_test.rb:
148
+ comments:
149
+ reviewed_by: shilpigoeldev
150
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
151
+ test/way_of_working/decision_record/madr/generators/new_test.rb:
152
+ comments:
153
+ reviewed_by: shilpigoeldev
154
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
155
+ test/way_of_working/decision_record/madr/github_audit_rule_test.rb:
156
+ comments:
157
+ reviewed_by: shilpigoeldev
158
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
159
+ test/way_of_working/decision_record/madr/zeitwerk_loader_test.rb:
160
+ comments:
161
+ reviewed_by: shilpigoeldev
162
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
163
+ test/way_of_working/decision_record/madr_test.rb:
164
+ comments:
165
+ reviewed_by: timgentry
166
+ safe_revision: a73811b079389f4706d7f4dbe37ca461b2424642
167
+ way_of_working-decision_record-madr.gemspec:
168
+ comments:
169
+ reviewed_by: shilpigoeldev
170
+ safe_revision: 726c543149db70831ba9892789e93f7cb9bf6317
data/docs/decisions/0000-use-markdown-any-decision-records.md ADDED
@@ -0,0 +1,30 @@
1
+ ---
2
+ nav_order: 0
3
+ parent: Decision Records
4
+ ---
5
+ # Use Markdown Any Decision Records
6
+
7
+ ## Context and Problem Statement
8
+
9
+ We want to record any decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
10
+ Which format and structure should these records follow?
11
+
12
+ ## Considered Options
13
+
14
+ * [MADR](https://adr.github.io/madr/) 3.0.0 – The Markdown Any Decision Records
15
+ * [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
16
+ * [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
17
+ * Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
18
+ * Formless – No conventions for file format and structure
19
+
20
+ ## Decision Outcome
21
+
22
+ Chosen option: "MADR 3.0.0", because
23
+
24
+ * Implicit assumptions should be made explicit.
25
+ Design documentation is important to enable people understanding the decisions later on.
26
+ See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
27
+ * MADR allows for structured capturing of any decision.
28
+ * The MADR format is lean and fits our development style.
29
+ * The MADR structure is comprehensible and facilitates usage & maintenance.
30
+ * The MADR project is vivid.
data/docs/decisions/README.md ADDED
@@ -0,0 +1,7 @@
1
+ # Decisions
2
+
3
+ This directory contains decision records for the project.
4
+
5
+ For new ADRs, please use [adr-template.md](adr-template.md) as basis.
6
+ More information on MADR is available at <https://adr.github.io/madr/>.
7
+ General information about architectural decision records is available at <https://adr.github.io/>.
data/docs/decisions/adr-template.md ADDED
@@ -0,0 +1,82 @@
1
+ ---
2
+ nav_order: {index}
3
+ parent: Decision Records
4
+
5
+ # These are optional elements. Feel free to remove any of them.
6
+ status: {proposed | rejected | accepted | deprecated | … | superseded by ADR-0005 <0005-example.md>}
7
+ date: {YYYY-MM-DD when the decision was last updated}
8
+ deciders: {list everyone involved in the decision}
9
+ consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
10
+ informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
11
+ ---
12
+ # {short title of solved problem and solution}
13
+
14
+ ## Context and Problem Statement
15
+
16
+ {Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
17
+ You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
18
+
19
+ <!-- This is an optional element. Feel free to remove. -->
20
+ ## Decision Drivers
21
+
22
+ * {decision driver 1, e.g., a force, facing concern, …}
23
+ * {decision driver 2, e.g., a force, facing concern, …}
24
+ * … <!-- numbers of drivers can vary -->
25
+
26
+ ## Considered Options
27
+
28
+ * {title of option 1}
29
+ * {title of option 2}
30
+ * {title of option 3}
31
+ * … <!-- numbers of options can vary -->
32
+
33
+ ## Decision Outcome
34
+
35
+ Chosen option: "{title of option 1}", because
36
+ {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
37
+
38
+ <!-- This is an optional element. Feel free to remove. -->
39
+ ### Consequences
40
+
41
+ * Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
42
+ * Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
43
+ * … <!-- numbers of consequences can vary -->
44
+
45
+ <!-- This is an optional element. Feel free to remove. -->
46
+ ## Validation
47
+
48
+ {describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}
49
+
50
+ <!-- This is an optional element. Feel free to remove. -->
51
+ ## Pros and Cons of the Options
52
+
53
+ ### {title of option 1}
54
+
55
+ <!-- This is an optional element. Feel free to remove. -->
56
+ {example | description | pointer to more information | …}
57
+
58
+ * Good, because {argument a}
59
+ * Good, because {argument b}
60
+ <!-- use "neutral" if the given argument weights neither for good nor bad -->
61
+ * Neutral, because {argument c}
62
+ * Bad, because {argument d}
63
+ * … <!-- numbers of pros and cons can vary -->
64
+
65
+ ### {title of other option}
66
+
67
+ {example | description | pointer to more information | …}
68
+
69
+ * Good, because {argument a}
70
+ * Good, because {argument b}
71
+ * Neutral, because {argument c}
72
+ * Bad, because {argument d}
73
+ * …
74
+
75
+ <!-- This is an optional element. Feel free to remove. -->
76
+ ## More Information
77
+
78
+ {You might want to provide additional evidence/confidence for the decision outcome here and/or
79
+ document the team agreement on the decision and/or
80
+ define when and how this decision should be realized and if/when it should be re-visited and/or
81
+ how the decision is validated.
82
+ Links to other decisions and resources might appear here as well.}
data/docs/decisions/index.md ADDED
@@ -0,0 +1,48 @@
1
+ ---
2
+ has_children: true
3
+ ---
4
+ # Decision Records
5
+
6
+ We use [Markdown Any Decision Records (MADR)](https://adr.github.io/madr/) version 3.0.0.
7
+
8
+ In general, projects will follow the organisation's way of working and so decisions captured within individual projects will generally cover decisions that:
9
+
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
13
+
14
+ ## Create a new decision record
15
+
16
+ ### Manual approach
17
+
18
+ 1. Copy `docs/decisions/adr-template.md` to `docs/decisions/NNNN-title-with-dashes.md`, where `NNNN` indicates the next number in sequence.
19
+ 2. Edit `NNNN-title-with-dashes.md`.
20
+
21
+ Note you can also use [other patterns for the directory format](https://github.com/joelparkerhenderson/architecture_decision_record#adr-file-name-conventions).
22
+ As a consequence, some existing tooling might not be applicable.
23
+
24
+ The filenames are following the pattern `NNNN-title-with-dashes.md`, where
25
+
26
+ - `NNNN` is a consecutive number and we assume that there won't be more than 9,999 ADRs in one repository.
27
+ - the title is stored using dashes and lowercase, because [adr-tools] also does that.
28
+ - the suffix is `.md`, because it is a [Markdown](https://github.github.com/gfm/) file.
29
+
30
+ Decisions are placed in the subfolder `decisions/` to keep them close to the documentation but also separate the decisions from other documentation.
31
+
32
+ ### Automatic approach
33
+
34
+ To create a new decision record, run:
35
+
36
+ ```bash
37
+ way_of_working new decision_record [NAME]
38
+ ```
39
+
40
+ Where `[NAME]` is the title of your decision record, for example:
41
+
42
+ ```bash
43
+ way_of_working new decision_record "Use Markdown Any Decision Records"
44
+ ```
45
+
46
+ ## Project decision records
47
+
48
+ Decision records for this project are listed below.
data/docs/way_of_working/decision-records.md ADDED
@@ -0,0 +1,58 @@
1
+ ---
2
+ layout: page
3
+ ---
4
+ # Decision Records
5
+
6
+ We use [Markdown Any Decision Records (MADR)](https://adr.github.io/madr/) version 3.0.0.
7
+
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:
9
+
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
13
+
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/>.
15
+
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).
17
+
18
+ ## Usage
19
+
20
+ ### Adding Markdown Any Decision Records to your project
21
+
22
+ To add the MADR v3.0.0 framework to your project, run the following at the command line:
23
+
24
+ ```bash
25
+ way_of_working init decision_record
26
+ ```
27
+
28
+ ### Create a new decision record
29
+
30
+ #### Manual approach
31
+
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`.
34
+
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.
37
+
38
+ The filenames are following the pattern `NNNN-title-with-dashes.md`, where
39
+
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.
43
+
44
+ Decisions are placed in the subfolder `decisions/` to keep them close to the documentation but also separate the decisions from other documentation.
45
+
46
+ #### Automatic approach
47
+
48
+ To create a new decision record, run:
49
+
50
+ ```bash
51
+ way_of_working new decision_record [NAME]
52
+ ```
53
+
54
+ Where `[NAME]` is the title of your decision record, for example:
55
+
56
+ ```bash
57
+ way_of_working new decision_record "Use Markdown Any Decision Records"
58
+ ```
data/lib/way_of_working/decision_record/madr/generators/init.rb ADDED
@@ -0,0 +1,41 @@
1
+ # frozen_string_literal: true
2
+
3
+ module WayOfWorking
4
+ module DecisionRecord
5
+ module Madr
6
+ module Generators
7
+ # This generator add the MADR files to the doc/decisions folder
8
+ class Init < Thor::Group
9
+ include Thor::Actions
10
+
11
+ source_root ::WayOfWorking::DecisionRecord::Madr.source_root
12
+
13
+ def copy_decision_record_issue_template
14
+ copy_file '.github/ISSUE_TEMPLATE/decision-record.md'
15
+ end
16
+
17
+ # Templates are from https://github.com/adr/madr/tree/3.0.0/template
18
+ def create_decision_record_files
19
+ copy_file 'docs/decisions/README.md'
20
+
21
+ # from https://raw.githubusercontent.com/adr/madr/3.0.0/template/adr-template.md
22
+ @decision_date = '{YYYY-MM-DD when the decision was last updated}'
23
+ @index = '{index}'
24
+ @title = '{short title of solved problem and solution}'
25
+ template 'docs/decisions/adr-template.md'
26
+
27
+ copy_file 'docs/decisions/0000-use-markdown-any-decision-records.md'
28
+ end
29
+
30
+ def copy_index_file
31
+ copy_file 'docs/decisions/index.md'
32
+ end
33
+
34
+ def copy_way_of_working_file
35
+ copy_file 'docs/way_of_working/decision-records.md'
36
+ end
37
+ end
38
+ end
39
+ end
40
+ end
41
+ end
data/lib/way_of_working/decision_record/madr/generators/new.rb ADDED
@@ -0,0 +1,69 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'date'
4
+
5
+ module WayOfWorking
6
+ module DecisionRecord
7
+ module Madr
8
+ module Generators
9
+ # This generator add a new MADR decision record to the doc/decisions folder
10
+ class New < Thor::Group
11
+ argument :name, type: :string, required: true, desc: 'The title of the decision record'
12
+
13
+ include Thor::Actions
14
+
15
+ source_root ::WayOfWorking::DecisionRecord::Madr.source_root
16
+
17
+ def create_decision_record_file
18
+ case behavior
19
+ when :invoke
20
+ invoke_decision_record_file
21
+ when :revoke
22
+ revoke_decision_record_file
23
+ end
24
+ end
25
+
26
+ private
27
+
28
+ def invoke_decision_record_file
29
+ @decision_date = Date.today.strftime('%Y-%m-%d')
30
+ @index = next_decision_number.to_i
31
+ @title = name
32
+
33
+ # from https://raw.githubusercontent.com/adr/madr/3.0.0/template/adr-template.md
34
+ template 'docs/decisions/adr-template.md',
35
+ "docs/decisions/#{next_decision_number}-#{dashed_name}.md"
36
+ end
37
+
38
+ def revoke_decision_record_file
39
+ matching_files = Dir.glob("[0-9][0-9][0-9][0-9]-#{dashed_name}.md",
40
+ base: File.join(destination_root, 'docs/decisions'))
41
+ raise "No matching decision record for '#{dashed_name}'" if matching_files.empty?
42
+
43
+ # based on Thor's remove_file
44
+ path = File.expand_path("docs/decisions/#{matching_files.first}", destination_root)
45
+
46
+ say_status :remove, relative_to_original_destination_root(path)
47
+ return unless !options[:pretend] && (File.exist?(path) || File.symlink?(path))
48
+
49
+ require 'fileutils'
50
+ ::FileUtils.rm_rf(path)
51
+ end
52
+
53
+ def next_decision_number
54
+ existing_decisions = Dir.glob('[0-9][0-9][0-9][0-9]-*.md',
55
+ base: File.join(destination_root, 'docs/decisions'))
56
+ last_number = existing_decisions.map do |filename|
57
+ filename.match(/\A(\d{4})-/)[1].to_i
58
+ end.max || -1
59
+ format('%04d', last_number + 1)
60
+ end
61
+
62
+ def dashed_name
63
+ name.downcase.gsub(/[\s_()]/, '-').gsub(/-+/, '-')
64
+ end
65
+ end
66
+ end
67
+ end
68
+ end
69
+ end
data/lib/way_of_working/decision_record/madr/github_audit_rule.rb ADDED
@@ -0,0 +1,44 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'way_of_working/audit/github/rules/base'
4
+
5
+ module WayOfWorking
6
+ module DecisionRecord
7
+ # The namespace for plugin
8
+ module Madr
9
+ # This rule checks for the MADR Decision Record template.
10
+ class GithubAuditRule < ::WayOfWorking::Audit::Github::Rules::Base
11
+ ADR_TEMPLATE_PATH = 'docs/decisions/adr-template.md'
12
+ DECISION_ZERO_PATH = 'docs/decisions/0000-use-markdown-any-decision-records.md'
13
+
14
+ source_root ::WayOfWorking::DecisionRecord::Madr.source_root
15
+
16
+ def validate
17
+ @errors << 'No MADR Decision Record template found' unless repo_file_contains?(
18
+ ADR_TEMPLATE_PATH, '## Context and Problem Statement'
19
+ )
20
+ return if repo_file_contains_source_file?(DECISION_ZERO_PATH)
21
+
22
+ @errors << 'No 0000-use-markdown-any-decision-records.md Decision Record found'
23
+ end
24
+
25
+ private
26
+
27
+ def repo_file_contains_source_file?(path)
28
+ repo_file_contains?(path, File.read(self.class.source_root.join(path)))
29
+ end
30
+
31
+ def repo_file_contains?(path, text)
32
+ remote_content = repo_file_contents(path)
33
+ return false if remote_content.nil?
34
+
35
+ remote_content.include?(text)
36
+ end
37
+ end
38
+
39
+ ::WayOfWorking::Audit::Github::Rules::Registry.register(
40
+ GithubAuditRule, 'MADR Decision Records'
41
+ )
42
+ end
43
+ end
44
+ end
data/lib/way_of_working/decision_record/madr/paths.rb ADDED
@@ -0,0 +1,20 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'pathname'
4
+
5
+ module WayOfWorking
6
+ module DecisionRecord
7
+ # Mixin that provides a couple of pathname convenience methods
8
+ module Madr
9
+ class << self
10
+ def root
11
+ Pathname.new(File.expand_path('../../../..', __dir__))
12
+ end
13
+
14
+ def source_root
15
+ root.join('lib', 'way_of_working', 'decision_record', 'madr', 'templates')
16
+ end
17
+ end
18
+ end
19
+ end
20
+ end
data/lib/way_of_working/decision_record/madr/plugin.rb ADDED
@@ -0,0 +1 @@
1
+ require 'way_of_working/decision_record/madr'
data/lib/way_of_working/decision_record/madr/templates/.github/ISSUE_TEMPLATE/decision-record.md ADDED
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: Decision Record
3
+ about: Create a ticket to discuss or propose a new decision record
4
+ title: ''
5
+ labels: decision record
6
+ assignees: ''
7
+
8
+ ---
9
+ ## Context and Problem Statement
10
+
11
+ {Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
12
+ You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
13
+
14
+ <!-- This is an optional element. Feel free to remove. -->
15
+ ## Decision Drivers
16
+
17
+ * {decision driver 1, e.g., a force, facing concern, …}
18
+ * {decision driver 2, e.g., a force, facing concern, …}
19
+ * … <!-- numbers of drivers can vary -->
20
+
21
+ ## Considered Options
22
+
23
+ * {title of option 1}
24
+ * {title of option 2}
25
+ * {title of option 3}
26
+ * … <!-- numbers of options can vary -->
data/lib/way_of_working/decision_record/madr/templates/docs/decisions/0000-use-markdown-any-decision-records.md ADDED
@@ -0,0 +1,30 @@
1
+ ---
2
+ nav_order: 0
3
+ parent: Decision Records
4
+ ---
5
+ # Use Markdown Any Decision Records
6
+
7
+ ## Context and Problem Statement
8
+
9
+ We want to record any decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
10
+ Which format and structure should these records follow?
11
+
12
+ ## Considered Options
13
+
14
+ * [MADR](https://adr.github.io/madr/) 3.0.0 – The Markdown Any Decision Records
15
+ * [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
16
+ * [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
17
+ * Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
18
+ * Formless – No conventions for file format and structure
19
+
20
+ ## Decision Outcome
21
+
22
+ Chosen option: "MADR 3.0.0", because
23
+
24
+ * Implicit assumptions should be made explicit.
25
+ Design documentation is important to enable people understanding the decisions later on.
26
+ See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
27
+ * MADR allows for structured capturing of any decision.
28
+ * The MADR format is lean and fits our development style.
29
+ * The MADR structure is comprehensible and facilitates usage & maintenance.
30
+ * The MADR project is vivid.
data/lib/way_of_working/decision_record/madr/templates/docs/decisions/README.md ADDED
@@ -0,0 +1,7 @@
1
+ # Decisions
2
+
3
+ This directory contains decision records for the project.
4
+
5
+ For new ADRs, please use [adr-template.md](adr-template.md) as basis.
6
+ More information on MADR is available at <https://adr.github.io/madr/>.
7
+ General information about architectural decision records is available at <https://adr.github.io/>.
data/lib/way_of_working/decision_record/madr/templates/docs/decisions/adr-template.md.tt ADDED
@@ -0,0 +1,82 @@
1
+ ---
2
+ nav_order: <%= @index %>
3
+ parent: Decision Records
4
+
5
+ # These are optional elements. Feel free to remove any of them.
6
+ status: {proposed | rejected | accepted | deprecated | … | superseded by ADR-0005 <0005-example.md>}
7
+ date: <%= @decision_date %>
8
+ deciders: {list everyone involved in the decision}
9
+ consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
10
+ informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
11
+ ---
12
+ # <%= @title %>
13
+
14
+ ## Context and Problem Statement
15
+
16
+ {Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
17
+ You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
18
+
19
+ <!-- This is an optional element. Feel free to remove. -->
20
+ ## Decision Drivers
21
+
22
+ * {decision driver 1, e.g., a force, facing concern, …}
23
+ * {decision driver 2, e.g., a force, facing concern, …}
24
+ * … <!-- numbers of drivers can vary -->
25
+
26
+ ## Considered Options
27
+
28
+ * {title of option 1}
29
+ * {title of option 2}
30
+ * {title of option 3}
31
+ * … <!-- numbers of options can vary -->
32
+
33
+ ## Decision Outcome
34
+
35
+ Chosen option: "{title of option 1}", because
36
+ {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
37
+
38
+ <!-- This is an optional element. Feel free to remove. -->
39
+ ### Consequences
40
+
41
+ * Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
42
+ * Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
43
+ * … <!-- numbers of consequences can vary -->
44
+
45
+ <!-- This is an optional element. Feel free to remove. -->
46
+ ## Validation
47
+
48
+ {describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}
49
+
50
+ <!-- This is an optional element. Feel free to remove. -->
51
+ ## Pros and Cons of the Options
52
+
53
+ ### {title of option 1}
54
+
55
+ <!-- This is an optional element. Feel free to remove. -->
56
+ {example | description | pointer to more information | …}
57
+
58
+ * Good, because {argument a}
59
+ * Good, because {argument b}
60
+ <!-- use "neutral" if the given argument weights neither for good nor bad -->
61
+ * Neutral, because {argument c}
62
+ * Bad, because {argument d}
63
+ * … <!-- numbers of pros and cons can vary -->
64
+
65
+ ### {title of other option}
66
+
67
+ {example | description | pointer to more information | …}
68
+
69
+ * Good, because {argument a}
70
+ * Good, because {argument b}
71
+ * Neutral, because {argument c}
72
+ * Bad, because {argument d}
73
+ * …
74
+
75
+ <!-- This is an optional element. Feel free to remove. -->
76
+ ## More Information
77
+
78
+ {You might want to provide additional evidence/confidence for the decision outcome here and/or
79
+ document the team agreement on the decision and/or
80
+ define when and how this decision should be realized and if/when it should be re-visited and/or
81
+ how the decision is validated.
82
+ Links to other decisions and resources might appear here as well.}
data/lib/way_of_working/decision_record/madr/templates/docs/decisions/index.md ADDED
@@ -0,0 +1,48 @@
1
+ ---
2
+ has_children: true
3
+ ---
4
+ # Decision Records
5
+
6
+ We use [Markdown Any Decision Records (MADR)](https://adr.github.io/madr/) version 3.0.0.
7
+
8
+ In general, projects will follow the organisation's way of working and so decisions captured within individual projects will generally cover decisions that:
9
+
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
13
+
14
+ ## Create a new decision record
15
+
16
+ ### Manual approach
17
+
18
+ 1. Copy `docs/decisions/adr-template.md` to `docs/decisions/NNNN-title-with-dashes.md`, where `NNNN` indicates the next number in sequence.
19
+ 2. Edit `NNNN-title-with-dashes.md`.
20
+
21
+ Note you can also use [other patterns for the directory format](https://github.com/joelparkerhenderson/architecture_decision_record#adr-file-name-conventions).
22
+ As a consequence, some existing tooling might not be applicable.
23
+
24
+ The filenames are following the pattern `NNNN-title-with-dashes.md`, where
25
+
26
+ - `NNNN` is a consecutive number and we assume that there won't be more than 9,999 ADRs in one repository.
27
+ - the title is stored using dashes and lowercase, because [adr-tools] also does that.
28
+ - the suffix is `.md`, because it is a [Markdown](https://github.github.com/gfm/) file.
29
+
30
+ Decisions are placed in the subfolder `decisions/` to keep them close to the documentation but also separate the decisions from other documentation.
31
+
32
+ ### Automatic approach
33
+
34
+ To create a new decision record, run:
35
+
36
+ ```bash
37
+ way_of_working new decision_record [NAME]
38
+ ```
39
+
40
+ Where `[NAME]` is the title of your decision record, for example:
41
+
42
+ ```bash
43
+ way_of_working new decision_record "Use Markdown Any Decision Records"
44
+ ```
45
+
46
+ ## Project decision records
47
+
48
+ Decision records for this project are listed below.
data/lib/way_of_working/decision_record/madr/templates/docs/way_of_working/decision-records.md ADDED
@@ -0,0 +1,58 @@
1
+ ---
2
+ layout: page
3
+ ---
4
+ # Decision Records
5
+
6
+ We use [Markdown Any Decision Records (MADR)](https://adr.github.io/madr/) version 3.0.0.
7
+
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:
9
+
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
13
+
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/>.
15
+
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).
17
+
18
+ ## Usage
19
+
20
+ ### Adding Markdown Any Decision Records to your project
21
+
22
+ To add the MADR v3.0.0 framework to your project, run the following at the command line:
23
+
24
+ ```bash
25
+ way_of_working init decision_record
26
+ ```
27
+
28
+ ### Create a new decision record
29
+
30
+ #### Manual approach
31
+
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`.
34
+
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.
37
+
38
+ The filenames are following the pattern `NNNN-title-with-dashes.md`, where
39
+
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.
43
+
44
+ Decisions are placed in the subfolder `decisions/` to keep them close to the documentation but also separate the decisions from other documentation.
45
+
46
+ #### Automatic approach
47
+
48
+ To create a new decision record, run:
49
+
50
+ ```bash
51
+ way_of_working new decision_record [NAME]
52
+ ```
53
+
54
+ Where `[NAME]` is the title of your decision record, for example:
55
+
56
+ ```bash
57
+ way_of_working new decision_record "Use Markdown Any Decision Records"
58
+ ```
data/lib/way_of_working/decision_record/madr/version.rb ADDED
@@ -0,0 +1,9 @@
1
+ # frozen_string_literal: true
2
+
3
+ module WayOfWorking
4
+ module DecisionRecord
5
+ module Madr
6
+ VERSION = '1.0.0'
7
+ end
8
+ end
9
+ end
data/lib/way_of_working/decision_record/madr.rb ADDED
@@ -0,0 +1,58 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'way_of_working'
4
+ require_relative 'madr/paths'
5
+ require 'zeitwerk'
6
+
7
+ # If way_of_working-audit-github is used we can add a rule
8
+ begin
9
+ require 'way_of_working/audit/github/rules/registry'
10
+ require_relative 'madr/github_audit_rule'
11
+ rescue LoadError # rubocop:disable Lint/SuppressedException
12
+ end
13
+
14
+ loader = Zeitwerk::Loader.for_gem_extension(WayOfWorking::DecisionRecord)
15
+ loader.ignore("#{__dir__}/madr/plugin.rb")
16
+ loader.setup
17
+
18
+ module WayOfWorking
19
+ module DecisionRecord
20
+ module Madr
21
+ class Error < StandardError; end
22
+ end
23
+ end
24
+
25
+ module SubCommands
26
+ # This reopens the "way_of_working init" sub command
27
+ class Init
28
+ register(DecisionRecord::Madr::Generators::Init, 'decision_record', 'decision_record',
29
+ <<~LONGDESC)
30
+ Description:
31
+ This generator adds Markdown Any Decision Records (MADR) to your project
32
+
33
+ Example:
34
+ way_of_working init decision_record
35
+
36
+ This will create:
37
+ docs/decisions/README.md
38
+ docs/decisions/adr-template.md
39
+ docs/decisions/0000-use-markdown-any-decision-records.md
40
+ LONGDESC
41
+ end
42
+
43
+ # This reopens the "way_of_working new" sub command
44
+ class New
45
+ register(DecisionRecord::Madr::Generators::New, 'decision_record', 'decision_record [NAME]',
46
+ <<~LONGDESC)
47
+ Description:
48
+ This generator adds a new decision record to your project
49
+
50
+ Example:
51
+ way_of_working new decision_record "Title of the decision"
52
+
53
+ This will create:
54
+ docs/decisions/NNNN-title-of-the-decision.md
55
+ LONGDESC
56
+ end
57
+ end
58
+ end
metadata ADDED
@@ -0,0 +1,101 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: way_of_working-decision_record-madr
3
+ version: !ruby/object:Gem::Version
4
+ version: 1.0.0
5
+ platform: ruby
6
+ authors:
7
+ - Tim Gentry
8
+ autorequire:
9
+ bindir: exe
10
+ cert_chain: []
11
+ date: 2025-01-23 00:00:00.000000000 Z
12
+ dependencies:
13
+ - !ruby/object:Gem::Dependency
14
+ name: way_of_working
15
+ requirement: !ruby/object:Gem::Requirement
16
+ requirements:
17
+ - - "~>"
18
+ - !ruby/object:Gem::Version
19
+ version: '2.0'
20
+ type: :runtime
21
+ prerelease: false
22
+ version_requirements: !ruby/object:Gem::Requirement
23
+ requirements:
24
+ - - "~>"
25
+ - !ruby/object:Gem::Version
26
+ version: '2.0'
27
+ - !ruby/object:Gem::Dependency
28
+ name: zeitwerk
29
+ requirement: !ruby/object:Gem::Requirement
30
+ requirements:
31
+ - - "~>"
32
+ - !ruby/object:Gem::Version
33
+ version: 2.6.18
34
+ type: :runtime
35
+ prerelease: false
36
+ version_requirements: !ruby/object:Gem::Requirement
37
+ requirements:
38
+ - - "~>"
39
+ - !ruby/object:Gem::Version
40
+ version: 2.6.18
41
+ description:
42
+ email:
43
+ - 52189+timgentry@users.noreply.github.com
44
+ executables: []
45
+ extensions: []
46
+ extra_rdoc_files: []
47
+ files:
48
+ - ".mega-linter.yml"
49
+ - ".rubocop"
50
+ - CHANGELOG.md
51
+ - LICENSE.txt
52
+ - README.md
53
+ - Rakefile
54
+ - code_safety.yml
55
+ - docs/decisions/0000-use-markdown-any-decision-records.md
56
+ - docs/decisions/README.md
57
+ - docs/decisions/adr-template.md
58
+ - docs/decisions/index.md
59
+ - docs/way_of_working/decision-records.md
60
+ - lib/way_of_working/decision_record/madr.rb
61
+ - lib/way_of_working/decision_record/madr/generators/init.rb
62
+ - lib/way_of_working/decision_record/madr/generators/new.rb
63
+ - lib/way_of_working/decision_record/madr/github_audit_rule.rb
64
+ - lib/way_of_working/decision_record/madr/paths.rb
65
+ - lib/way_of_working/decision_record/madr/plugin.rb
66
+ - lib/way_of_working/decision_record/madr/templates/.github/ISSUE_TEMPLATE/decision-record.md
67
+ - lib/way_of_working/decision_record/madr/templates/docs/decisions/0000-use-markdown-any-decision-records.md
68
+ - lib/way_of_working/decision_record/madr/templates/docs/decisions/README.md
69
+ - lib/way_of_working/decision_record/madr/templates/docs/decisions/adr-template.md.tt
70
+ - lib/way_of_working/decision_record/madr/templates/docs/decisions/index.md
71
+ - lib/way_of_working/decision_record/madr/templates/docs/way_of_working/decision-records.md
72
+ - lib/way_of_working/decision_record/madr/version.rb
73
+ homepage: https://github.com/HealthDataInsight/way_of_working-decision_record-madr
74
+ licenses:
75
+ - MIT
76
+ metadata:
77
+ allowed_push_host: https://rubygems.org
78
+ rubygems_mfa_required: 'true'
79
+ homepage_uri: https://github.com/HealthDataInsight/way_of_working-decision_record-madr
80
+ source_code_uri: https://github.com/HealthDataInsight/way_of_working-decision_record-madr
81
+ changelog_uri: https://github.com/HealthDataInsight/way_of_working-decision_record-madr/blob/main/CHANGELOG.md
82
+ post_install_message:
83
+ rdoc_options: []
84
+ require_paths:
85
+ - lib
86
+ required_ruby_version: !ruby/object:Gem::Requirement
87
+ requirements:
88
+ - - ">="
89
+ - !ruby/object:Gem::Version
90
+ version: 3.0.0
91
+ required_rubygems_version: !ruby/object:Gem::Requirement
92
+ requirements:
93
+ - - ">="
94
+ - !ruby/object:Gem::Version
95
+ version: '0'
96
+ requirements: []
97
+ rubygems_version: 3.5.22
98
+ signing_key:
99
+ specification_version: 4
100
+ summary: Way of Working plugin for Decision Records using MADR v3
101
+ test_files: []