way_of_working 2.0.1 → 2.1.0

data/lib/way_of_working/inclusive_language/alex/github_audit_rule.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'way_of_working/audit/github/rules/base'
+
+module WayOfWorking
+  module InclusiveLanguage
+    # The namespace for plugin
+    module Alex
+      # This rule checks for the Inclusive Language workflow action and README badge.
+      class GithubAuditRule < ::WayOfWorking::Audit::Github::Rules::Base
+        def validate
+          response = @client.workflows(@repo_name)
+
+          unless response.workflows.map(&:name).include?('Inclusive Language')
+            @errors << 'No Inclusive Language GitHub Action'
+          end
+
+          @errors << 'Default branch is named "master"' if @repo.default_branch == 'master'
+
+          @errors << 'No Inclusive Language README Badge' unless inclusive_language_badge?
+        end
+
+        private
+
+        def inclusive_language_badge?
+          readme_content.include?("[![Inclusive Language](https://github.com/#{@repo_name}/actions/workflows/inclusive-language.yml/badge.svg)]")
+        end
+      end
+
+      ::WayOfWorking::Audit::Github::Rules::Registry.register(
+        GithubAuditRule, 'Inclusive Language GitHub Action and README badge'
+      )
+    end
+  end
+end

data/lib/way_of_working/inclusive_language/alex/templates/.alexignore

@@ -0,0 +1,2 @@
+/CODE_OF_CONDUCT.md
+/docs/way_of_working/code-of-conduct.md

data/lib/way_of_working/inclusive_language/alex/templates/.alexrc

@@ -0,0 +1,3 @@
+{
+  "profanitySureness": 1
+}

data/lib/way_of_working/inclusive_language/alex/templates/.github/workflows/inclusive-language.yml

@@ -0,0 +1,16 @@
+---
+name: "Inclusive Language"
+on: push  # yamllint disable-line rule:truthy
+
+permissions: read-all
+
+jobs:
+  test_inclusivity:
+    name: Inclusive Language Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Node via mise
+        uses: jdx/mise-action@v2
+      - name: Run alex
+        run: npx alex --why

data/lib/way_of_working/inclusive_language/alex/templates/docs/way_of_working/inclusive-language.md

@@ -0,0 +1,28 @@
+---
+layout: page
+---
+
+# Inclusive Language
+
+We have adopted [alex](https://alexjs.com) for automated testing of inclusive language.
+
+Using insensitive and inconsiderate language can cause harm to others, create barriers to communication, and damage relationships. It can make people feel excluded, disrespected, and devalued and may perpetuate negative stereotypes and biases. When we use insensitive or offensive language, we undermine our ability to connect with others and build trust.
+
+Therefore, it is essential to be mindful of the impact of our words and to choose language that is respectful, inclusive, and considerate of others. Doing so can create a more welcoming and inclusive environment for everyone, fostering greater understanding, empathy, and cooperation.
+
+To quote from the alex README:
+
+> No automated tool can replace studying inclusive communication and listening to the lived experiences of others. **An error from alex can be an invitation to learn more**.
+
+{: .important }
+Please take the opportunity to read some of the [further reading](https://github.com/get-alex/alex#further-reading) they reference and click on the links against individual warnings when they appear.
+
+## Usage
+
+To add alex to your project, run the following at the command line:
+
+    way_of_working init inclusive_language
+
+to run alex in your project, run:
+
+    way_of_working exec inclusive_language

data/lib/way_of_working/inclusive_language/alex.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'alex/generators/exec'
+require_relative 'alex/generators/init'
+
+# If way_of_working-audit-github is used we can add a rule
+begin
+  require 'way_of_working/audit/github/rules/registry'
+  require_relative 'alex/github_audit_rule'
+rescue LoadError # rubocop:disable Lint/SuppressedException
+end
+
+module WayOfWorking
+  module InclusiveLanguage
+    module Alex
+      class Error < StandardError; end
+    end
+  end
+
+  module SubCommands
+    # This reopens the "way_of_working exec" (i.e. run) sub command
+    class Exec
+      register(InclusiveLanguage::Alex::Generators::Exec, 'inclusive_language', 'inclusive_language',
+               <<~LONGDESC)
+                 Description:
+                     This runs inclusive language tests on this project
+
+                 Example:
+                     way_of_working exec inclusive_language
+               LONGDESC
+    end
+
+    # This reopens the "way_of_working init" sub command
+    class Init
+      register(InclusiveLanguage::Alex::Generators::Init, 'inclusive_language', 'inclusive_language',
+               <<~LONGDESC)
+                 Description:
+                     Installs alex config file into the project
+
+                 Example:
+                     way_of_working init inclusive_language
+
+                     This will create:
+                         .alexrc
+               LONGDESC
+    end
+  end
+end

data/lib/way_of_working/pull_request_template/hdi/generators/init.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module WayOfWorking
+  module PullRequestTemplate
+    module Hdi
+      module Generators
+        # This generator adds the Pull Request template to a project
+        class Init < Thor::Group
+          include Thor::Actions
+
+          source_root WayOfWorking.root.join('lib', 'way_of_working', 'pull_request_template', 'hdi', 'templates')
+
+          def copy_pr_template_action
+            copy_file '.github/pull_request_template.md'
+          end
+
+          def copy_way_of_working_documentation
+            copy_file 'docs/way_of_working/pull-request-template-and-guidelines.md'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/way_of_working/pull_request_template/hdi/github_audit_rule.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'way_of_working/audit/github/rules/base'
+
+module WayOfWorking
+  module PullRequestTemplate
+    # The namespace for plugin
+    module Hdi
+      # This rule checks for the Pull Request template.
+      class GithubAuditRule < ::WayOfWorking::Audit::Github::Rules::Base
+        def validate
+          @errors << 'No Way of Working Pull Request template found' unless pull_request_template?
+        end
+
+        private
+
+        def pull_request_template?
+          response = @client.contents(@repo_name, path: '.github/pull_request_template.md')
+          decoded_content = Base64.decode64(response.content)
+
+          decoded_content.include?('## Screenshots (optional)')
+        rescue Octokit::NotFound
+          false
+        end
+      end
+
+      ::WayOfWorking::Audit::Github::Rules::Registry.register(
+        GithubAuditRule, 'Pull Request template'
+      )
+    end
+  end
+end

data/lib/way_of_working/pull_request_template/hdi/templates/.github/pull_request_template.md

@@ -0,0 +1,51 @@
+# Pull Request Details
+
+## What?
+
+{Please write a few concise sentences outlining your changes and their overall impact, avoiding overly technical language. Reference relevant issue tracker tickets, but provide a stand-alone description that doesn’t require more than a few seconds to grasp.
+
+e.g. I've added support for authentication to implement feature X of service Y. It
+includes model, table, controller and test. For more background, see ticket #JIRA-123.}
+
+## Why?
+
+{Outlining the business or engineering goals this Pull Request accomplishes is often more important than the "what". For instance, adding an environment variable default value may appear uncomplicated to many. However, if it drastically alters the usage of libraries in your application, an active-voiced explanation is needed to capture the true impact of the change.
+
+e.g. These changes complete the user login and account creation experience. See #JIRA-123 for more information.}
+
+## How?
+
+{While the Pull Request diff illustrates the "how" of your changes, it's crucial to highlight major design decisions like choosing a recursive method over a loop. Explaining your reasoning helps reviewers understand your thought process and enables a more insightful review.
+
+e.g. This includes a migration, model and controller for user authentication. I'm using Devise to do the heavy lifting. I ran Devise migrations and those are included here.}
+
+## Testing?
+
+{Including tests along with code updates is essential as it prevents merging code without tests or failing tests, which could pose risks if overlooked. It's equally important to describe how you've tested harder-to-test code, like infrastructure code, and to communicate any untested conditions or edge cases and their associated risks to the reviewer.}
+
+## AI Contribution
+
+{Disclose any AI tools (e.g. GitHub Copilot, ChatGPT, Claude) used in this Pull Request, describing what they contributed. This helps reviewers understand the level of AI involvement and apply appropriate scrutiny.
+
+e.g. Claude 9.9 wrote the documentation and tests, or a team of GPT-9o agents wrote everything.}
+
+## Screenshots (optional)
+
+{Screenshots can significantly aid the review process, especially for UI-related changes, by offering before-and-after views. Even for backend code, a snapshot of the outcome, such as a CLI tool output, can be insightful. For infrastructure code, consider including the result of operations like a Terraform plan, preferably in a collapsible section, to avoid cluttering the comment space.
+
+Here’s how to do it in GitHub:
+```
+<details>
+  <summary>Terraform Plan</summary>
+
+  ### After running plan:
+</details>
+```
+}
+
+## Anything Else?
+
+{Consider discussing potential architectural modifications and technical debt while highlighting any challenges or optimisations you have identified.
+
+e.g. Let's consider using a 3rd party authentication provider for this, to offload MFA and other considerations as they arise and the privacy landscape evolves. AWS Cognito is a good option, so is Firebase. I'm happy to start researching this path.
+Let's also consider breaking this out into its own service. We can then re-use it or share the accounts with other apps in the future.}

data/lib/way_of_working/pull_request_template/hdi/templates/docs/way_of_working/pull-request-template-and-guidelines.md

@@ -0,0 +1,50 @@
+---
+layout: page
+status: REQUIRED
+enforcement: manual
+---
+
+# Pull Request Template and Guidelines
+
+## Purpose
+
+Standardise PR submissions to ensure consistent context, improve review efficiency, and maintain searchable project history.
+
+## Scope
+
+Applies to all pull requests across team projects.
+
+## Requirements
+
+- PR template must be present in repository
+- All PRs must include:
+  - Summary of changes
+  - Rationale (why)
+  - Associated issue/ticket numbers
+- Follow [Code of Conduct](code-of-conduct.md) and GitHub's [How to write the perfect pull request][perfect-pr] guidelines
+
+{: .important }
+A Pull Request doesn't begin and end with the template. The tone of the request and any subsequent feedback is also very important. Read GitHub's PR communication guidelines in [How to write the perfect pull request][perfect-pr].
+
+## Setup
+
+Initialise PR template:
+
+```bash
+way_of_working init pull_request_template
+```
+
+## Usage
+
+Use the template when creating PRs. Provide all requested information professionally.
+
+## Enforcement
+
+Manual review during PR submission and code review process.
+
+## Resources
+
+- [How to write the perfect pull request][perfect-pr]
+- [Code of Conduct](code-of-conduct.md)
+
+[perfect-pr]: https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/

data/lib/way_of_working/pull_request_template/hdi.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'hdi/generators/init'
+
+# If way_of_working-audit-github is used we can add a rule
+begin
+  require 'way_of_working/audit/github/rules/registry'
+  require_relative 'hdi/github_audit_rule'
+rescue LoadError # rubocop:disable Lint/SuppressedException
+end
+
+module WayOfWorking
+  module PullRequestTemplate
+    module Hdi
+      class Error < StandardError; end
+    end
+  end
+
+  module SubCommands
+    # This reopens the "way_of_working init" sub command
+    class Init
+      register(PullRequestTemplate::Hdi::Generators::Init, 'pull_request_template', 'pull_request_template',
+               <<~LONGDESC)
+                 Description:
+                     Installs the Pull Request template into the project
+
+                 Example:
+                     way_of_working init pull_request_template
+
+                     This will create:
+                         .github/pull_request_template.md
+               LONGDESC
+    end
+  end
+end

data/lib/way_of_working/readme_badge/paths.rb

@@ -3,9 +3,10 @@
 require 'pathname'
 
 module WayOfWorking
-  # Mixin that provides a couple of pathname convenience methods
+  # Namespace for the internal ReadmeBadge plugin
   module ReadmeBadge
-    class << self
+    # Mixin that provides a couple of pathname convenience methods
+    module Paths
       def root
         Pathname.new(File.expand_path('../../..', __dir__))
       end
@@ -14,5 +15,7 @@ module WayOfWorking
         root.join('lib', 'way_of_working', 'readme_badge', 'templates')
       end
     end
+
+    extend Paths
   end
 end

data/lib/way_of_working/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WayOfWorking
-  VERSION = '2.0.1'
+  VERSION = '2.1.0'
 end

data/lib/way_of_working/versioning/semver/generators/init.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module WayOfWorking
+  module Versioning
+    module Semver
+      module Generators
+        # This generator add the Semver files to the doc/decisions folder
+        class Init < Thor::Group
+          include Thor::Actions
+
+          source_root WayOfWorking.root.join('lib', 'way_of_working', 'versioning', 'semver', 'templates')
+
+          def copy_way_of_working_file
+            copy_file 'docs/way_of_working/versioning.md'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/way_of_working/versioning/semver/github_audit_rule.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'way_of_working/audit/github/rules/base'
+
+module WayOfWorking
+  module Versioning
+    # The namespace for this plugin
+    module Semver
+      # This rule checks for the versioning documentation
+      class GithubAuditRule < ::WayOfWorking::Audit::Github::Rules::Base
+        source_root WayOfWorking.root.join('lib', 'way_of_working', 'versioning', 'semver', 'templates')
+
+        def validate
+          validate_repo_file_contains_source_file(
+            'docs/way_of_working/versioning.md'
+          )
+        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
+
+        def validate_repo_file_contains_source_file(*paths)
+          paths.each do |path|
+            if repo_file_contents(path).nil?
+              @errors << "#{path} missing"
+              next
+            end
+
+            @errors << "#{path} does not match the source template" unless repo_file_contains_source_file?(path)
+          end
+        end
+      end
+
+      ::WayOfWorking::Audit::Github::Rules::Registry.register(
+        GithubAuditRule, 'Semantic Versioning'
+      )
+    end
+  end
+end

data/lib/way_of_working/versioning/semver/templates/docs/way_of_working/versioning.md

@@ -0,0 +1,71 @@
+---
+layout: page
+status: REQUIRED
+enforcement: manual
+---
+
+# Versioning
+
+## Purpose
+
+Define the versioning standard for communicating software changes and managing releases across projects.
+
+## Scope
+
+Applies to all software projects requiring version identification.
+
+## Requirements
+
+Use [Semantic Versioning](https://semver.org) (semver) with format `MAJOR.MINOR.PATCH`:
+
+1. **MAJOR**: Increment for incompatible API changes
+2. **MINOR**: Increment for backwards-compatible functionality additions
+3. **PATCH**: Increment for backwards-compatible bug fixes
+
+Pre-release and build metadata labels available as extensions.
+
+## Setup
+
+No specific tooling required. Apply version numbers to:
+
+- Git tags
+- Package manifests (`package.json`, `Cargo.toml`, etc.)
+- Release notes
+- Documentation
+
+## Usage
+
+**When to increment:**
+
+- Breaking changes → increment MAJOR (e.g., 1.2.3 → 2.0.0)
+- New features (backwards-compatible) → increment MINOR (e.g., 1.2.3 → 1.3.0)
+- Bug fixes (backwards-compatible) → increment PATCH (e.g., 1.2.3 → 1.2.4)
+
+**Pre-release versions:** Append hyphen and identifiers (e.g., 1.0.0-alpha, 1.0.0-beta.1)
+
+**Build metadata:** Append plus sign and identifiers (e.g., 1.0.0+20240115)
+
+## Enforcement
+
+Manual enforcement through:
+
+- Code review verification
+- Release checklist validation
+- Automated CI checks (where configured)
+
+## Examples
+
+```text
+0.1.0     → Initial development
+1.0.0     → First stable release
+1.1.0     → Added new feature
+1.1.1     → Fixed bug
+2.0.0     → Breaking API change
+2.0.0-rc.1 → Release candidate
+1.2.3+build.456 → With build metadata
+```
+
+## Resources
+
+- [Semantic Versioning Specification](https://semver.org)
+- [Semver Calculator](https://semver.npmjs.com) - Determine version impact

data/lib/way_of_working/versioning/semver.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'semver/generators/init'
+
+# If way_of_working-audit-github is used we can add a rule
+begin
+  require 'way_of_working/audit/github/rules/registry'
+  require_relative 'semver/github_audit_rule'
+rescue LoadError # rubocop:disable Lint/SuppressedException
+end
+
+module WayOfWorking
+  module Versioning
+    module Semver
+      class Error < StandardError; end
+    end
+  end
+
+  module SubCommands
+    # This reopens the "way_of_working init" sub command
+    class Init
+      register(Versioning::Semver::Generators::Init, 'versioning', 'versioning',
+               <<~LONGDESC)
+                 Description:
+                     This generator adds Semantic Versioning to your project
+
+                 Example:
+                     way_of_working init versioning
+
+                     This will create:
+                         docs/way_of_working/versioning.md
+               LONGDESC
+    end
+  end
+end

data/lib/way_of_working.rb

@@ -8,6 +8,21 @@ require 'zeitwerk'
 require 'way_of_working/readme_badge'
 
 loader = Zeitwerk::Loader.for_gem
+# tasks.rb is a rake-task entrypoint, not a constant definition — exclude it
+# from Zeitwerk's file-to-constant expectations so downstream apps can
+# `require 'way_of_working/tasks'` from their Rakefile.
+loader.ignore(File.expand_path('way_of_working/tasks.rb', __dir__))
+# github_audit_rule.rb is loaded conditionally (only when the
+# way_of_working-audit-github plugin is present — see readme_badge.rb) and
+# requires a constant from that plugin at the top of the file. Exclude it
+# from Zeitwerk's eager-load walk so its absence doesn't break the loader.
+loader.ignore(File.expand_path('way_of_working/changelog/keepachangelog/github_audit_rule.rb', __dir__))
+loader.ignore(File.expand_path('way_of_working/code_of_conduct/contributor_covenant/github_audit_rule.rb', __dir__))
+loader.ignore(File.expand_path('way_of_working/decision_record/madr/github_audit_rule.rb', __dir__))
+loader.ignore(File.expand_path('way_of_working/inclusive_language/alex/github_audit_rule.rb', __dir__))
+loader.ignore(File.expand_path('way_of_working/pull_request_template/hdi/github_audit_rule.rb', __dir__))
+loader.ignore(File.expand_path('way_of_working/readme_badge/github_audit_rule.rb', __dir__))
+loader.ignore(File.expand_path('way_of_working/versioning/semver/github_audit_rule.rb', __dir__))
 loader.setup
 
 # This is the namespace for everything associated with the Way of Working

data/way_of_working.gemspec

@@ -38,8 +38,11 @@ Gem::Specification.new do |spec|
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html
   spec.add_dependency 'activesupport'
+  spec.add_dependency 'faraday-multipart', '~> 1.0'
+  spec.add_dependency 'faraday-retry', '~> 2.2'
   spec.add_dependency 'git', '~> 1.13'
   spec.add_dependency 'nokogiri'
+  spec.add_dependency 'octokit', '~> 9.1'
   spec.add_dependency 'rainbow', '~> 3.1'
   spec.add_dependency 'thor', '~> 1.2'
   spec.add_dependency 'zeitwerk', '~> 2.6.18'