way_of_working 2.0.1 → 2.1.0

data/lib/way_of_working/decision_record/madr/generators/new.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module WayOfWorking
+  module DecisionRecord
+    module Madr
+      module Generators
+        # This generator add a new MADR decision record to the doc/decisions folder
+        class New < Thor::Group
+          argument :name, type: :string, required: true, desc: 'The title of the decision record'
+
+          include Thor::Actions
+
+          source_root WayOfWorking.root.join('lib', 'way_of_working', 'decision_record', 'madr', 'templates')
+
+          def create_decision_record_file
+            case behavior
+            when :invoke
+              invoke_decision_record_file
+            when :revoke
+              revoke_decision_record_file
+            end
+          end
+
+          private
+
+          def invoke_decision_record_file
+            @decision_date = Date.today.strftime('%Y-%m-%d')
+            @index = next_decision_number.to_i
+            @title = name
+
+            # from https://raw.githubusercontent.com/adr/madr/3.0.0/template/adr-template.md
+            template 'docs/decisions/adr-template.md',
+                     "docs/decisions/#{next_decision_number}-#{dashed_name}.md"
+          end
+
+          def revoke_decision_record_file
+            matching_files = Dir.glob("[0-9][0-9][0-9][0-9]-#{dashed_name}.md",
+                                      base: File.join(destination_root, 'docs/decisions'))
+            raise "No matching decision record for '#{dashed_name}'" if matching_files.empty?
+
+            # based on Thor's remove_file
+            path = File.expand_path("docs/decisions/#{matching_files.first}", destination_root)
+
+            say_status :remove, relative_to_original_destination_root(path)
+            return unless !options[:pretend] && (File.exist?(path) || File.symlink?(path))
+
+            require 'fileutils'
+            ::FileUtils.rm_rf(path)
+          end
+
+          def next_decision_number
+            existing_decisions = Dir.glob('[0-9][0-9][0-9][0-9]-*.md',
+                                          base: File.join(destination_root, 'docs/decisions'))
+            last_number = existing_decisions.map do |filename|
+              filename.match(/\A(\d{4})-/)[1].to_i
+            end.max || -1
+            format('%04d', last_number + 1)
+          end
+
+          def dashed_name
+            name.downcase.gsub(/[\s_()]/, '-').gsub(/-+/, '-')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/way_of_working/decision_record/madr/github_audit_rule.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'way_of_working/audit/github/rules/base'
+
+module WayOfWorking
+  module DecisionRecord
+    # The namespace for plugin
+    module Madr
+      # This rule checks for the MADR Decision Record template.
+      class GithubAuditRule < ::WayOfWorking::Audit::Github::Rules::Base
+        ADR_TEMPLATE_PATH = 'docs/decisions/adr-template.md'
+        DECISION_ZERO_PATH = 'docs/decisions/0000-use-markdown-any-decision-records.md'
+        WOW_DOCUMENTATION_PATH = 'docs/way_of_working/decision-records.md'
+
+        source_root WayOfWorking.root.join('lib', 'way_of_working', 'decision_record', 'madr', 'templates')
+
+        def validate
+          @errors << 'No MADR Decision Record template found' unless repo_file_contains?(
+            ADR_TEMPLATE_PATH, '## Context and Problem Statement'
+          )
+
+          unless repo_file_contains_source_file?(WOW_DOCUMENTATION_PATH)
+            @errors << 'Stale or missing documentation for using MADR Decision Records'
+          end
+
+          return if repo_file_contains_source_file?(DECISION_ZERO_PATH)
+
+          @errors << 'No 0000-use-markdown-any-decision-records.md Decision Record found'
+        end
+
+        private
+
+        def repo_file_contains_source_file?(path)
+          repo_file_contains?(path, File.read(self.class.source_root.join(path)))
+        end
+
+        def repo_file_contains?(path, text)
+          remote_content = repo_file_contents(path)
+          return false if remote_content.nil?
+
+          remote_content.include?(text)
+        end
+      end
+
+      ::WayOfWorking::Audit::Github::Rules::Registry.register(
+        GithubAuditRule, 'MADR Decision Records'
+      )
+    end
+  end
+end

data/lib/way_of_working/decision_record/madr/templates/.github/ISSUE_TEMPLATE/decision-record.md

@@ -0,0 +1,26 @@
+---
+name: Decision Record
+about: Create a ticket to discuss or propose a new decision record
+title: ''
+labels: decision record
+assignees: ''
+
+---
+## Context and Problem Statement
+
+{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
+ You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
+
+<!-- This is an optional element. Feel free to remove. -->
+## Decision Drivers
+
+* {decision driver 1, e.g., a force, facing concern, …}
+* {decision driver 2, e.g., a force, facing concern, …}
+* … <!-- numbers of drivers can vary -->
+
+## Considered Options
+
+* {title of option 1}
+* {title of option 2}
+* {title of option 3}
+* … <!-- numbers of options can vary -->

data/lib/way_of_working/decision_record/madr/templates/docs/decisions/0000-use-markdown-any-decision-records.md

@@ -0,0 +1,30 @@
+---
+nav_order: 0
+parent: Decision Records
+---
+# Use Markdown Any Decision Records
+
+## Context and Problem Statement
+
+We want to record any decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
+Which format and structure should these records follow?
+
+## Considered Options
+
+* [MADR](https://adr.github.io/madr/) 3.0.0 – The Markdown Any Decision Records
+* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
+* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+* Formless – No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 3.0.0", because
+
+* Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+* MADR allows for structured capturing of any decision.
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.

data/lib/way_of_working/decision_record/madr/templates/docs/decisions/README.md

@@ -0,0 +1,7 @@
+# Decisions
+
+This directory contains decision records for the project.
+
+For new ADRs, please use [adr-template.md](adr-template.md) as basis.
+More information on MADR is available at <https://adr.github.io/madr/>.
+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

@@ -0,0 +1,82 @@
+---
+nav_order: <%= @index %>
+parent: Decision Records
+
+# These are optional elements. Feel free to remove any of them.
+status: {proposed | rejected | accepted | deprecated | … | superseded by ADR-0005 <0005-example.md>}
+date: <%= @decision_date %>
+deciders: {list everyone involved in the decision}
+consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
+informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
+---
+# <%= @title %>
+
+## Context and Problem Statement
+
+{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
+ You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
+
+<!-- This is an optional element. Feel free to remove. -->
+## Decision Drivers
+
+* {decision driver 1, e.g., a force, facing concern, …}
+* {decision driver 2, e.g., a force, facing concern, …}
+* … <!-- numbers of drivers can vary -->
+
+## Considered Options
+
+* {title of option 1}
+* {title of option 2}
+* {title of option 3}
+* … <!-- numbers of options can vary -->
+
+## Decision Outcome
+
+Chosen option: "{title of option 1}", because
+{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
+
+<!-- This is an optional element. Feel free to remove. -->
+### Consequences
+
+* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
+* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
+* … <!-- numbers of consequences can vary -->
+
+<!-- This is an optional element. Feel free to remove. -->
+## Validation
+
+{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}
+
+<!-- This is an optional element. Feel free to remove. -->
+## Pros and Cons of the Options
+
+### {title of option 1}
+
+<!-- This is an optional element. Feel free to remove. -->
+{example | description | pointer to more information | …}
+
+* Good, because {argument a}
+* Good, because {argument b}
+<!-- use "neutral" if the given argument weights neither for good nor bad -->
+* Neutral, because {argument c}
+* Bad, because {argument d}
+* … <!-- numbers of pros and cons can vary -->
+
+### {title of other option}
+
+{example | description | pointer to more information | …}
+
+* Good, because {argument a}
+* Good, because {argument b}
+* Neutral, because {argument c}
+* Bad, because {argument d}
+* …
+
+<!-- This is an optional element. Feel free to remove. -->
+## More Information
+
+{You might want to provide additional evidence/confidence for the decision outcome here and/or
+ document the team agreement on the decision and/or
+ define when and how this decision should be realized and if/when it should be re-visited and/or
+ how the decision is validated.
+ Links to other decisions and resources might appear here as well.}

data/lib/way_of_working/decision_record/madr/templates/docs/decisions/index.md

@@ -0,0 +1,48 @@
+---
+has_children: true
+---
+# Decision Records
+
+We use [Markdown Any Decision Records (MADR)](https://adr.github.io/madr/) version 3.0.0.
+
+In general, projects will follow the organisation's way of working and so decisions captured within individual projects will generally cover decisions that:
+
+- are not already covered in the Way of Working
+- are covered in the Way of Working, but have specific implementation details which need to be captured
+- diverge from the guidance in the Way of Working
+
+## Create a new decision record
+
+### Manual approach
+
+1. Copy `docs/decisions/adr-template.md` to `docs/decisions/NNNN-title-with-dashes.md`, where `NNNN` indicates the next number in sequence.
+2. Edit `NNNN-title-with-dashes.md`.
+
+Note you can also use [other patterns for the directory format](https://github.com/joelparkerhenderson/architecture_decision_record#adr-file-name-conventions).
+As a consequence, some existing tooling might not be applicable.
+
+The filenames are following the pattern `NNNN-title-with-dashes.md`, where
+
+- `NNNN` is a consecutive number and we assume that there won't be more than 9,999 ADRs in one repository.
+- the title is stored using dashes and lowercase, because [adr-tools] also does that.
+- the suffix is `.md`, because it is a [Markdown](https://github.github.com/gfm/) file.
+
+Decisions are placed in the subfolder `decisions/` to keep them close to the documentation but also separate the decisions from other documentation.
+
+### Automatic approach
+
+To create a new decision record, run:
+
+```bash
+way_of_working new decision_record [NAME]
+```
+
+Where `[NAME]` is the title of your decision record, for example:
+
+```bash
+way_of_working new decision_record "Use Markdown Any Decision Records"
+```
+
+## Project decision records
+
+Decision records for this project are listed below.

data/lib/way_of_working/decision_record/madr/templates/docs/way_of_working/decision-records.md

@@ -0,0 +1,195 @@
+---
+layout: page
+status: REQUIRED
+enforcement: manual
+---
+# Decision Records
+
+## Purpose
+
+We use [Markdown Any Decision Records (MADR)][madr] v3.0.0 to capture project decisions that:
+
+- aren't covered in the [Way of Working][wow]
+- need project-specific implementation details
+- diverge from Way of Working guidance
+
+{: .note }
+Proposing and reviewing decisions requires familiarity with [GitHub pull requests][gh-pr].
+
+## Scope
+
+Applies to decisions about:
+
+- **Architecture**: System design, technology stack, frameworks
+- **Process**: Development workflows, deployment, testing
+- **Code standards**: Patterns, conventions, library usage
+- **Dependencies**: Adding/removing major libraries or services
+- **Data**: Schema changes, migration strategies
+
+**Create ADR when:**
+
+- Impact spans multiple components or teams
+- Long-term consequences or significant cost/risk
+- Multiple viable alternatives exist
+
+**Don't create ADR for:**
+
+- Already covered by Way of Working
+- Tactical implementation details (use code comments)
+- Temporary workarounds or clear-cut choices
+
+## Requirements
+
+**File naming:** `NNNN-title-with-dashes.md`
+
+- `NNNN` = consecutive four-digit number (0001, 0002, etc.)
+- Lowercase title with dashes
+- Located in `docs/decisions/`
+
+**Required content:**
+
+1. Status (proposed, accepted, rejected, deprecated, superseded)
+2. Context and problem statement
+3. Considered options (minimum 2)
+4. Decision outcome with justification
+5. Positive and negative consequences
+
+**Status lifecycle:**
+
+- **proposed** - Under discussion
+- **accepted** - Approved for implementation
+- **rejected** - Decided against
+- **deprecated** - No longer relevant
+- **superseded** - Replaced by newer ADR (link required)
+
+## Setup
+
+```bash
+way_of_working init decision_record
+```
+
+## Usage
+
+### Create a new decision record
+
+```bash
+way_of_working new decision_record "Use Markdown Any Decision Records"
+```
+
+**Propose decision:**
+
+1. Create ADR with status "proposed"
+2. Open PR, tag stakeholders
+3. Discuss in PR comments
+4. Update to "accepted" once consensus reached
+5. Merge PR
+
+**Supersede existing ADR:**
+
+1. Create new ADR
+2. Update old ADR status to "superseded by [0XXX-new-title.md](0XXX-new-title.md)"
+3. Explain what changed in new ADR
+
+## Enforcement
+
+**PR Review:**
+
+- All ADRs submitted via PR
+- Maintainer approval required
+- Verify MADR template structure, file naming, location
+- Check minimum 2 options with justification
+
+**Quality checklist:**
+
+- ✅ Multiple alternatives with pros/cons
+- ✅ Clear context and constraints
+- ✅ Explicit trade-offs
+- ❌ Only one option presented
+- ❌ Missing justification or context
+
+**Maintenance:**
+
+- Quarterly review for relevance
+- Update deprecated/superseded status as needed
+
+## Examples
+
+**Database choice:**
+
+```markdown
+# Use PostgreSQL for Primary Database
+
+**Status:** accepted
+**Date:** 2025-10-15
+
+## Context and Problem Statement
+
+Need relational database for user data with complex relationships.
+Constraints: ACID compliance, 100K users/1M records, prefer open-source.
+
+## Considered Options
+
+1. PostgreSQL (self-hosted)
+2. MySQL
+3. RDS PostgreSQL
+
+## Decision Outcome
+
+**Chosen:** PostgreSQL (self-hosted)
+
+**Pros:** Open-source, advanced features (JSON, full-text search), ACID, team experience
+**Cons:** DevOps overhead, manual backup, manual scaling
+
+**Why:** Meets requirements within budget. Cloud-managed exceeds budget by 40%.
+Team expertise mitigates complexity.
+
+**Alternatives rejected:**
+- MySQL: No advantage over PostgreSQL
+- RDS: Cost $200-500/month exceeds budget
+```
+
+**Superseded ADR:**
+
+```markdown
+# Use Jest for Frontend Testing
+
+**Status:** superseded by [0015-use-vitest.md](0015-use-vitest.md)
+**Date:** 2025-01-10 (original), 2025-09-15 (superseded)
+
+**Why superseded:** Vitest now standard for Vite projects,
+better integration and performance.
+```
+
+**Rejected decision:**
+
+```markdown
+# Use GraphQL for API Layer
+
+**Status:** rejected
+**Date:** 2025-03-20
+
+## Decision Outcome
+
+**Chosen:** Continue with REST API
+
+**Why rejected:**
+- Current REST meets all requirements
+- Team lacks GraphQL expertise (4-6 week learning curve)
+- Migration cost: 8 engineer-weeks
+- No client needs GraphQL features
+
+**Reconsider when:** Multiple clients need flexible fetching
+or over-fetching impacts performance.
+```
+
+## Resources
+
+- [MADR Documentation][madr]
+- [GDS Architecture Decisions][gds-way]
+- [Way of Working CLI][wow-cli]
+
+[madr]: https://adr.github.io/madr/
+[wow]: https://github.com/HealthDataInsight/way_of_working
+[gds-way]: https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html
+[gh-pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
+[wow-cli]: ../cli.md

data/lib/way_of_working/decision_record/madr.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'madr/generators/init'
+require_relative 'madr/generators/new'
+
+# If way_of_working-audit-github is used we can add a rule
+begin
+  require 'way_of_working/audit/github/rules/registry'
+  require_relative 'madr/github_audit_rule'
+rescue LoadError # rubocop:disable Lint/SuppressedException
+end
+
+module WayOfWorking
+  module DecisionRecord
+    module Madr
+      class Error < StandardError; end
+    end
+  end
+
+  module SubCommands
+    # This reopens the "way_of_working init" sub command
+    class Init
+      register(DecisionRecord::Madr::Generators::Init, 'decision_record', 'decision_record',
+               <<~LONGDESC)
+                 Description:
+                     This generator adds Markdown Any Decision Records (MADR) to your project
+
+                 Example:
+                     way_of_working init decision_record
+
+                     This will create:
+                         docs/decisions/README.md
+                         docs/decisions/adr-template.md
+                         docs/decisions/0000-use-markdown-any-decision-records.md
+               LONGDESC
+    end
+
+    # This reopens the "way_of_working new" sub command
+    class New
+      register(DecisionRecord::Madr::Generators::New, 'decision_record', 'decision_record [NAME]',
+               <<~LONGDESC)
+                 Description:
+                     This generator adds a new decision record to your project
+
+                 Example:
+                     way_of_working new decision_record "Title of the decision"
+
+                     This will create:
+                         docs/decisions/NNNN-title-of-the-decision.md
+               LONGDESC
+    end
+  end
+end

data/lib/way_of_working/git/repo_reader.rb

@@ -58,10 +58,10 @@ module WayOfWorking
 
       def likely_upstream_remote
         remotes = @base.remotes
-        return remotes.first if remotes.count == 1
+        return remotes.first if remotes.one?
 
         remotes = remotes.reject { |remote| remote.name == 'origin' }
-        return remotes.first if remotes.count == 1
+        return remotes.first if remotes.one?
 
         remotes.last
       end

data/lib/way_of_working/inclusive_language/alex/generators/exec.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'rainbow'
+
+module WayOfWorking
+  module InclusiveLanguage
+    module Alex
+      module Generators
+        # This generator runs the inclusive language tests
+        class Exec < Thor::Group
+          argument :path, type: :string, required: false, desc: 'Optional path of the file to test'
+
+          desc 'This runs the inclusive language tests on this project'
+
+          def run_first
+            @start_time = Time.now
+
+            say(Rainbow("Limiting tests to #{path}\n").yellow) if path
+          end
+
+          def prep_and_run_alex
+            command = ['npx', 'alex', '--why']
+            # Configure alex to only test a specific file or folder, if defined
+            command << path if path
+
+            say(Rainbow("\nRunning alex...").yellow)
+
+            @alex_ok = run_alex(command)
+          end
+
+          def run_last
+            say(Rainbow("\nTotal time taken: #{(Time.now - @start_time).to_i} seconds").yellow)
+
+            if @alex_ok
+              say(Rainbow("\nInclusive language tests succeeded!").green)
+            else
+              abort(Rainbow("\nInclusive language tests failed!").red)
+            end
+          end
+
+          private
+
+          def run_alex(arguments)
+            system(*arguments)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/way_of_working/inclusive_language/alex/generators/init.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module WayOfWorking
+  module InclusiveLanguage
+    module Alex
+      module Generators
+        # This generator adds the alexrc file
+        class Init < Thor::Group
+          include Thor::Actions
+
+          source_root WayOfWorking.root.join('lib', 'way_of_working', 'inclusive_language', 'alex', 'templates')
+
+          def copy_inclusive_language_github_workflow_action
+            copy_file '.github/workflows/inclusive-language.yml'
+          end
+
+          def copy_alexignore_file
+            copy_file '.alexignore'
+          end
+
+          def copy_alexrc_file
+            copy_file '.alexrc'
+          end
+
+          def copy_way_of_working_documentation
+            copy_file 'docs/way_of_working/inclusive-language.md'
+          end
+        end
+      end
+    end
+  end
+end