way_of_working 2.0.1 → 2.1.0

data/lib/way_of_working/audit/github/rules/unknown.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module WayOfWorking
+  module Audit
+    module Github
+      module Rules
+        # This is a stub handler for rules that aren't in the registry.
+        class Unknown < Base
+          def initialize(client, name, repo, rulesets, fix = false)
+            super
+            raise 'Error: Unknown client'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/way_of_working/audit/github.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'github/generators/exec'
+
+module WayOfWorking
+  module Audit
+    module Github
+      class Error < StandardError; end
+    end
+  end
+
+  module SubCommands
+    # This reopens the "way_of_working exec" sub command
+    class Exec
+      register(Audit::Github::Generators::Exec, 'audit_github', 'audit_github',
+               <<~LONGDESC)
+                 Description:
+                     This runs the GitHub audit
+
+                 Example:
+                     way_of_working exec audit_github
+               LONGDESC
+    end
+  end
+end

data/lib/way_of_working/changelog/keepachangelog/generators/init.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'way_of_working/git/repo_reader'
+
+module WayOfWorking
+  module Changelog
+    module Keepachangelog
+      module Generators
+        # This class generates the CHANGELOG.md file, generating sections based on
+        # git tags and commit messages (where possible).
+        class Init < Thor::Group
+          include Thor::Actions
+
+          source_root WayOfWorking.root.join('lib', 'way_of_working', 'changelog', 'keepachangelog', 'templates')
+
+          HEADER_TEXT = <<~TEXT
+            # Changelog
+
+            All notable changes to this project will be documented in this file.
+
+            The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+            and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+          TEXT
+
+          def add_changelog_to_project
+            create_file 'CHANGELOG.md' do
+              HEADER_TEXT + releases + footer
+            end
+          end
+
+          def copy_way_of_working_documentation
+            copy_file 'docs/way_of_working/changelog.md'
+          end
+
+          private
+
+          def releases
+            text = "## [Unreleased]\n\n"
+            text += added_change_text(:minor)
+            text += deprecated_removed_fixed_security_text(:minor)
+
+            summary_tags.each do |summary_tag|
+              text += "## [#{summary_tag.version}] - " \
+                      "#{summary_tag.commit_date.strftime('%Y-%m-%d')}\n\n"
+
+              text += added_change_text(summary_tag.change_type)
+              text += deprecated_removed_fixed_security_text(summary_tag.change_type)
+            end
+
+            text
+          end
+
+          def added_change_text(tag_change_type)
+            return '' if tag_change_type == :patch
+
+            change_text('Added', 'Detail new feature(s) here', true) +
+              change_text('Change', 'Detail change(s) in existing functionality here',
+                          tag_change_type == :major)
+          end
+
+          def deprecated_removed_fixed_security_text(tag_change_type)
+            change_text('Deprecated', 'Detail soon-to-be removed features here') +
+              change_text('Removed', 'Detail removed features here', tag_change_type == :major) +
+              change_text('Fixed', 'Detail any bug fixes here', true) +
+              change_text('Security', 'Detail fixes to vulnerabilities here')
+          end
+
+          # This method adds all of the reference style markdown links
+          def footer
+            return '' if summary_tags.empty?
+
+            previous_tag = nil
+            footer_text = ''
+            summary_tags.each do |summary_tag|
+              footer_text += if previous_tag
+                               release_link(summary_tag.name, previous_tag.name, previous_tag.version)
+                             else
+                               release_link(summary_tag.name, 'HEAD', 'Unreleased')
+                             end
+
+              previous_tag = summary_tag
+            end
+
+            footer_text += "[#{previous_tag.version}]: #{url}/releases/tag/#{previous_tag.name}\n"
+
+            footer_text
+          end
+
+          def release_link(start_tag, end_tag, version)
+            "[#{version}]: #{url}/compare/#{start_tag}...#{end_tag}\n"
+          end
+
+          def change_text(type, description, likely = false)
+            text = "### #{type}\n\n- TODO: #{description}"
+            text += ' (if any)' unless likely
+            text += "\n\n"
+            text
+          end
+
+          def repo_reader
+            @repo_reader ||= ::WayOfWorking::Git::RepoReader.new(::Git.open('.'))
+          end
+
+          def summary_tags
+            @summary_tags ||= repo_reader.summary_tags.reverse
+          rescue ArgumentError
+            []
+          end
+
+          def url
+            @url ||= repo_reader.likely_upstream_remote_url
+          end
+        end
+      end
+    end
+  end
+end

data/lib/way_of_working/changelog/keepachangelog/github_audit_rule.rb

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

data/lib/way_of_working/changelog/keepachangelog/templates/docs/way_of_working/changelog.md

@@ -0,0 +1,73 @@
+---
+layout: page
+status: REQUIRED
+enforcement: manual
+---
+
+# Changelog
+
+![Keep a Changelog v1.1.0 badge][changelog-badge]
+
+## Purpose
+
+Maintain a human-readable project history that documents all notable changes between versions in plain English.
+
+## Scope
+
+All projects must maintain a changelog using [Keep a Changelog v1.1.0][keep-a-changelog] format.
+
+## Requirements
+
+- Human-written plain English summaries (not commit log dumps)
+- Entry for every version
+- Latest version listed first
+- Release date displayed for each version
+- Changes grouped by type: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`
+- Versions and sections must be linkable
+- Follow [Semantic Versioning][semver]
+- Update changelog within Pull Requests, not at release time
+
+## Setup
+
+Initialise a changelog for your project:
+
+```bash
+way_of_working init changelog
+```
+
+For git-based projects with existing releases, this scaffolds sections based on semantic version tags.
+
+## Usage
+
+1. Update the `Unreleased` section in each Pull Request
+2. Group changes under appropriate headings
+3. Write clear, user-focused descriptions
+4. Move `Unreleased` changes to a version section at release
+5. Use scaffolded commit links to document historical changes
+
+## Enforcement
+
+- Changelog updates required in Pull Request reviews
+- No automatic commit log dumps permitted
+
+## Examples
+
+```markdown
+## [1.2.0] - 2025-10-22
+
+### Added
+- User authentication via OAuth2
+- Export data to CSV functionality
+
+### Fixed
+- Memory leak in background job processor
+```
+
+## Resources
+
+- [Keep a Changelog][keep-a-changelog]
+- [Semantic Versioning][semver]
+
+[changelog-badge]: https://img.shields.io/badge/changelog-Keep%20a%20Changelog%20v1.1.0-%23E05735
+[keep-a-changelog]: https://keepachangelog.com/en/1.1.0/
+[semver]: https://semver.org

data/lib/way_of_working/changelog/keepachangelog.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'keepachangelog/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 'keepachangelog/github_audit_rule'
+rescue LoadError # rubocop:disable Lint/SuppressedException
+end
+
+module WayOfWorking
+  module Changelog
+    module Keepachangelog
+      class Error < StandardError; end
+    end
+  end
+
+  module SubCommands
+    # This reopens the "way_of_working init" sub command
+    class Init
+      register(Changelog::Keepachangelog::Generators::Init, 'changelog', 'changelog',
+               <<~LONGDESC)
+                 Description:
+                     This adds the Keep a Changelog v1.1 changelog to the project
+
+                 Example:
+                     way_of_working init changelog
+
+                     This will create:
+                     CHANGELOG.md
+               LONGDESC
+    end
+  end
+end

data/lib/way_of_working/code_of_conduct/contributor_covenant/generators/init.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'way_of_working/paths'
+
+module WayOfWorking
+  module CodeOfConduct
+    module ContributorCovenant
+      module Generators
+        # This class fetches the CODE_OF_CONDUCT.md and inserts the contact method
+        class Init < Thor::Group
+          include Thor::Actions
+
+          source_root WayOfWorking.root.join('lib', 'way_of_working', 'code_of_conduct', 'contributor_covenant',
+                                             'templates')
+
+          class_option :contact_method, required: true
+
+          # Use this method to update the cached template when required
+          # def download_and_save_code_of_conduct_template
+          #   code_of_conduct_file = 'lib/way_of_working/templates/CODE_OF_CONDUCT.md.tt'
+
+          #   get 'https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md',
+          #       code_of_conduct_file
+          #   gsub_file code_of_conduct_file, '[INSERT CONTACT METHOD]',
+          #             "<<%= options['contact_method'] %>>"
+          # end
+
+          def add_code_of_conduct_to_project
+            template 'CODE_OF_CONDUCT.md'
+          end
+
+          def add_way_of_working_documentation
+            copy_file 'docs/way_of_working/code-of-conduct.md'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/way_of_working/code_of_conduct/contributor_covenant/github_audit_rule.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'way_of_working/audit/github/rules/base'
+
+module WayOfWorking
+  module CodeOfConduct
+    # The namespace for this plugin
+    module ContributorCovenant
+      # This rule checks for the MegaLinter workflow action and README badge.
+      class GithubAuditRule < ::WayOfWorking::Audit::Github::Rules::Base
+        def validate
+          @errors << 'No Contributor Covenant code of conduct found' unless code_of_conduct?
+        end
+
+        private
+
+        def code_of_conduct?
+          response = @client.contents(@repo_name, path: 'CODE_OF_CONDUCT.md')
+          decoded_content = Base64.decode64(response.content)
+
+          decoded_content.include?('# Contributor Covenant Code of Conduct')
+        rescue Octokit::NotFound
+          false
+        end
+      end
+
+      ::WayOfWorking::Audit::Github::Rules::Registry.register(
+        GithubAuditRule, 'Contributor Covenant Code Of Conduct'
+      )
+    end
+  end
+end

data/lib/way_of_working/code_of_conduct/contributor_covenant/templates/CODE_OF_CONDUCT.md.tt

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not only for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+<<%= options['contact_method'] %>>.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

data/lib/way_of_working/code_of_conduct/contributor_covenant/templates/docs/way_of_working/code-of-conduct.md

@@ -0,0 +1,78 @@
+---
+layout: page
+status: REQUIRED
+enforcement: manual
+---
+# Code of Conduct
+
+## Purpose
+
+We adopt the [Contributor Covenant v2.1][covenant] to establish clear behavioural expectations, create safe inclusive environments, prevent discrimination/harassment, and reduce conflicts.
+
+{: .important }
+Adoption requires more than adding `CODE_OF_CONDUCT.md`. Please read the [enforcement guidelines][enforcement] and discuss with your team.
+
+## Scope
+
+Applies to all project spaces and community interactions.
+
+**Promotes:** Respectful communication, collaboration, inclusive language, professional conduct
+
+**Prevents:** Discrimination, harassment, unprofessional behaviour
+
+## Requirements
+
+1. Contact method for reports (email address)
+2. Enforcement responsibilities and process
+3. Consequences framework
+
+{: .note }
+Use HDI Code of Conduct email address as contact method.
+
+## Setup
+
+```bash
+way_of_working init code_of_conduct --contact-method [CONTACT METHOD]
+```
+
+## Usage
+
+Command creates `CODE_OF_CONDUCT.md` in repository root.
+
+**Post-setup:**
+
+1. Review enforcement guidelines with team
+2. Assign enforcement responsibilities
+3. Communicate adoption to contributors
+4. Link from README and CONTRIBUTING
+
+**Enforcement process:**
+Report → Review → Investigate → Apply consequence → Document
+
+## Enforcement
+
+**Consequences:**
+
+- **Warning:** First offense, minor issue
+- **Temporary ban:** Sustained inappropriate behavior
+- **Permanent ban:** Severe violations or repeat offenses
+
+**Requirements:**
+
+- Consistent enforcement by leadership
+- Confidential handling, 5-day response
+- Document incidents, annual review
+
+## Examples
+
+**Acceptable:** Welcoming language, respect differing views, accept criticism, focus on community benefit
+
+**Unacceptable:** Sexualized content, trolling/insults, harassment, publishing private info, unprofessional conduct
+
+## Resources
+
+- [Contributor Covenant v2.1][covenant]
+- [Enforcement Guidelines][enforcement]
+
+[covenant]: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+[enforcement]: https://www.contributor-covenant.org/version/2/1/code_of_conduct/#enforcement-guidelines

data/lib/way_of_working/code_of_conduct/contributor_covenant.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'contributor_covenant/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 'contributor_covenant/github_audit_rule'
+rescue LoadError # rubocop:disable Lint/SuppressedException
+end
+
+module WayOfWorking
+  module CodeOfConduct
+    module ContributorCovenant
+      class Error < StandardError; end
+    end
+  end
+
+  module SubCommands
+    # This reopens the "way_of_working init" sub command
+    class Init
+      register(CodeOfConduct::ContributorCovenant::Generators::Init, 'code_of_conduct',
+               'code_of_conduct --contact-method [CONTACT METHOD]',
+               <<~LONGDESC)
+                 Description:
+                     This adds the Contributor Covenant v2.1 code of conduct to the project
+
+                 Example:
+                     way_of_working init code_of_conduct --contact-method "foo@bar.com"
+
+                     This will create:
+                         CODE_OF_CONDUCT.md
+               LONGDESC
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module WayOfWorking
+  module DecisionRecord
+    module Madr
+      module Generators
+        # This generator add the MADR files to the doc/decisions folder
+        class Init < Thor::Group
+          include Thor::Actions
+
+          source_root WayOfWorking.root.join('lib', 'way_of_working', 'decision_record', 'madr', 'templates')
+
+          def copy_decision_record_issue_template
+            copy_file '.github/ISSUE_TEMPLATE/decision-record.md'
+          end
+
+          # Templates are from https://github.com/adr/madr/tree/3.0.0/template
+          def create_decision_record_files
+            copy_file 'docs/decisions/README.md'
+
+            # from https://raw.githubusercontent.com/adr/madr/3.0.0/template/adr-template.md
+            @decision_date = '{YYYY-MM-DD when the decision was last updated}'
+            @index = '{index}'
+            @title = '{short title of solved problem and solution}'
+            template 'docs/decisions/adr-template.md'
+
+            copy_file 'docs/decisions/0000-use-markdown-any-decision-records.md'
+          end
+
+          def copy_index_file
+            copy_file 'docs/decisions/index.md'
+          end
+
+          def copy_way_of_working_file
+            copy_file 'docs/way_of_working/decision-records.md'
+          end
+        end
+      end
+    end
+  end
+end