Way of Working

Way of Working Badge

Gem Version
MegaLinter Inclusive Language

Introduction

This tool underpins the Way of Working framework, used to describe a consistent, high-quality approach to Software Engineering. It is intended as an opinionated approach supporting rapid development, across numerous projects, by a fungible workforce who can swap between assignments with the minimum friction.

It consists command line tool that uses a modular, plugin-based system to gain functionality, allowing for organisations to pick and choose different solutions for the same feature. Organisations can create their own gem which defines the specific plugin dependencies which form their way of working. See the Way of Working for HDI as an example.

There are subcommands that plugins hook into which enable them to add GitHub actions, configuration and other files to a project and GitHub pages outlining the tooling choice and thinking behind it.

Below is a list of plugins that have been implemented so far:

Feature Plugin Description
Audit Built-in (audit/github) A framework for rules to check for incorrect content and configuration of GitHub repos — bundled, opt in by require (see Built-in Features)
Changelog Built-in (changelog/keepachangelog) Implements keepachangelog v1.1 — bundled, opt in by require (see Built-in Features)
Code Linting code_linting-hdi Implements a combination of MegaLinter and RuboCop built on NDRS standards
Code of Conduct Built-in (code_of_conduct/contributor_covenant) Implements Contributor Covenant v2.1 — bundled, opt in by require (see Built-in Features)
Decision Records Built-in (decision_record/madr) Implements MADR v3 — bundled, opt in by require (see Built-in Features)
Inclusive Language Built-in (inclusive_language/alex) Implements alex — bundled, opt in by require (see Built-in Features)
Pull Request Template Built-in (pull_request_template/hdi) Implements a bespoke PR template — bundled, opt in by require (see Built-in Features)
Versioning Built-in (versioning/semver) Implements Semantic Versioning v2.0.0 — bundled, opt in by require (see Built-in Features)

Some features are Built-in — they ship inside this gem and are enabled by requiring them (see Built-in Features); the others are separate plugin gems that you add as dependencies.

The standard versions cited above (Contributor Covenant v2.1, MADR v3, and so on) describe the content a feature generates, not the gem's interface. They advance through minor releases — see Versioning Policy.

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add way_of_working

If bundler is not being used to manage dependencies, install the gem by executing:

gem install way_of_working

Usage

Initialise All Components

To add all the Way of Working components to your project, run:

way_of_working init all --contact-method [CONTACT METHOD]

You will need to provide the Code of Conduct [CONTACT METHOD], usually an email address, for community leaders to receive reports of unacceptable behavior.

Built-in Features

Some features are bundled with this gem rather than shipped as separate plugins. These built-in features are opt in: enable one by requiring it wherever you load Way of Working — for example in your organisation's Way of Working gem, or in your project's Rakefile.

Audit

Auditing your GitHub repositories against a consistent set of rules catches missing or misconfigured files and repository settings across an organisation, keeping projects aligned with your way of working. Many of the other built-in features register their own rules to check that they have been adopted properly.

This feature provides a registry and auditing tool for GitHub repositories; rules can check for both missing/incorrect files and mis-configuration of the repository itself. Enable it by requiring it:

require 'way_of_working/audit/github'

The audit needs two environment variables:

  • GITHUB_ORGANISATION: the name of your organisation being scanned (as used in the GitHub URL)
  • GITHUB_TOKEN: a PAT token with sufficient permission to access repositories and their configuration

Once required, a subcommand becomes available. By default it runs only against repositories configured as git remotes in your current project:

# Audit this project's GitHub repositories
way_of_working exec audit_github

Flags let you widen or narrow the scope:

# Audit every repository in the organisation
way_of_working exec audit_github --all

# Filter to repositories carrying a topic
way_of_working exec audit_github --all --topic way-of-working

# Audit one or more repositories by name (implies the whole organisation)
way_of_working exec audit_github --name structured_store other_repo

# Audit only public repositories
way_of_working exec audit_github --all --public

# Attempt to automatically fix issues where rules support it
way_of_working exec audit_github --fix

Changelog

Keeping a curated, human-readable changelog helps users and contributors quickly see what has changed between releases without trawling through the commit history.

This feature uses Keep a Changelog v1.1 to generate a CHANGELOG.md, seeding it with sections derived from your git tags and commit messages where possible. Enable it by requiring it:

require 'way_of_working/changelog/keepachangelog'

Once required, a subcommand becomes available:

# Add a Keep a Changelog CHANGELOG.md and documentation to your project
way_of_working init changelog

Code of Conduct

A code of conduct sets clear expectations for acceptable behaviour within a community or project, helping to create a safer, more welcoming and inclusive environment and giving maintainers a basis for addressing inappropriate behaviour.

This feature installs the Contributor Covenant v2.1 code of conduct along with its accompanying documentation. Enable it by requiring it:

require 'way_of_working/code_of_conduct/contributor_covenant'

Once required, a subcommand becomes available:

# Add the Contributor Covenant code of conduct and documentation to your project
way_of_working init code_of_conduct --contact-method [CONTACT METHOD]

You will need to provide a [CONTACT METHOD], usually an email address, for community leaders to receive reports of unacceptable behavior.

Decision Records

Recording the context and reasoning behind significant decisions helps current and future contributors understand why a project is the way it is, avoids relitigating settled questions, and onboards newcomers faster.

This feature uses Markdown Any Decision Records (MADR) to capture decisions as version-controlled Markdown alongside your code. Enable it by requiring it:

require 'way_of_working/decision_record/madr'

Once required, two subcommands become available:

# Add the decision records index, template and first record to your project
way_of_working init decision_record

# Create a new decision record
way_of_working new decision_record "Title of the decision"

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.

This feature uses alex for automated testing of inclusive language, both at the command line and as a GitHub workflow. Enable it by requiring it:

require 'way_of_working/inclusive_language/alex'

Once required, two subcommands become available:

# Add the alex config, .alexignore, GitHub Action and documentation to your project
way_of_working init inclusive_language

# Run the inclusive language checks
way_of_working exec inclusive_language

Pull Request Template

A consistent pull request template standardises PR submissions, giving reviewers the context they need, improving review efficiency, and keeping a searchable project history.

This feature installs a bespoke HDI pull request template along with its accompanying guidelines documentation. Enable it by requiring it:

require 'way_of_working/pull_request_template/hdi'

Once required, a subcommand becomes available:

# Add the pull request template and documentation to your project
way_of_working init pull_request_template

Versioning

A shared versioning standard makes software changes clear to communicate and releases predictable to manage across projects, so consumers can reason about compatibility at a glance.

This feature documents Semantic Versioning v2.0.0 as the project's versioning standard. Enable it by requiring it:

require 'way_of_working/versioning/semver'

Once required, a subcommand becomes available:

# Add the Semantic Versioning documentation to your project
way_of_working init versioning

Help

More help on using the command line tool is found by using:

way_of_working help

Development

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. This RubyGem was created using bundle gem --exe way_of_working.

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.

When creating plugins, the convention is to create them within the WayOfWorking and feature namespaces. E.g.

Versioning Policy

This project follows Semantic Versioning, but SemVer governs the gem's public interface — the CLI commands and their options, the require paths of built-in features, and the plugin registration API — not the content of the artefacts its generators emit.

Consequently:

  • Refreshing the standard a feature embeds (e.g. a new Contributor Covenant or MADR version) is new behaviour → MINOR.
  • A bug fix in generation is PATCH.
  • MAJOR is reserved for breaking the interface above (renaming or removing a command or option, moving a require path, or changing the plugin API).

For a standard update drastic enough to surprise existing users, we add a new variant under the feature's category/variant namespace rather than mutating the existing one, so both coexist and consumers opt in by require path. This keeps the change additive (MINOR) and leaves existing users untouched.

See ADR-0001 for the full rationale and CONTRIBUTING.md for the version-bump checklist.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/HealthDataInsight/way_of_working. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

See CONTRIBUTING.md for development setup, the versioning policy and the release process.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the WayOfWorking project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.