way_of_working-for-hdi 1.0.0

data/docs/decisions/0004-end-to-end-aka-system-testing.md

@@ -0,0 +1,41 @@
+---
+# Configuration for the Jekyll template "Just the Docs"
+nav_order: 4
+parent: Decision Records
+
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+date: 2023-03-03
+---
+# End-to-End (aka System) Testing
+
+## Context and Problem Statement
+
+Many solutions are specific to the technology they are testing. We want to adopt an approach that enables contributors to read and write tests across projects without the brittleness of some solutions.
+
+Which should we choose?
+
+We should provide tooling around the edges that initially scaffolds the tool into a Rails application and creates a GitHub Action. Support for other tech stacks would follow.
+
+## Considered Options
+
+* [Cypress](https://www.cypress.io) JavaScript web testing and component testing framework.
+* [Capybara](http://teamcapybara.github.io/capybara/) using the [Selenium](https://www.selenium.dev) driver and Chrome browser (the Rails default).
+* [Capybara](http://teamcapybara.github.io/capybara/) using the [Cuprite](https://cuprite.rubycdp.com) driver and Chrome browser.
+
+## Decision Outcome
+
+Chosen option: "Cypress" because:
+* Although tests need to be written in JavaScript or TypeScript, the tested web application can be in any language. It also has a new experimental feature, where non-developers can click and record tests by interacting with the tested app.
+* Debugging (both the tested application and the tests themselves) is effortless, with "time travel" showing you what the app looked like at each test step.
+* It can be integrated into a Rails application using [cypress-rails](https://github.com/testdouble/cypress-rails). [CypressOnRails](https://github.com/shakacode/cypress-on-rails) was also considered.
+
+### Consequences
+
+* Good, because end-to-end testing increases the quality of our applications and reduces the chances of downtime or data loss.
+* Good, because we can spend more time creating end-to-end tests than fighting the test framework.
+* Neutral, because developers will need to introduce `data-test` HTML attributes into our applications to enable them to be reliably tested.
+
+## More Information
+
+In order to not delay the decision to adopt Cypress, the Rails initialisation tooling will be added later.

data/docs/decisions/0005-standardised-approach-to-versioning.md

@@ -0,0 +1,27 @@
+---
+# Configuration for the Jekyll template "Just the Docs"
+nav_order: 5
+parent: Decision Records
+
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+date: 2023-03-03
+---
+# Standardised approach to versioning
+
+## Context and Problem Statement
+
+"Dependency hell" is the complex and frustrating situation where a software project has multiple dependencies, but installing or updating one dependency leads to conflicts or incompatibilities with others, causing errors and delays in the development process.
+
+What version numbering scheme should we adopt to avoid dependency hell?
+
+## Considered Options
+
+* [Semantic Versioning](https://semver.org)
+* [Calendar Versioning](https://calver.org)
+
+## Decision Outcome
+
+Chosen option: "Semantic Versioning" because:
+* it is a well established and widely used version numbering scheme
+* allows us to quickly identify breaking changes to dependencies

data/docs/decisions/0006-standard-approach-to-automated-accessibility-testing.md

@@ -0,0 +1,54 @@
+---
+# Configuration for the Jekyll template "Just the Docs"
+nav_order: 6
+parent: Decision Records
+
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+date: 2023-03-03
+---
+# Standard approach to automated accessibility testing
+
+## Context and Problem Statement
+
+The services we design need to be accessible and meet WCAG 2.1 level AA as a minimum, preferably meeting WCAG 2.1 level AAA where possible.
+Alongside human auditing, we want a consistent approach to automated accessibility testing, so which tool should we choose?
+
+We should provide tooling around the edges that:
+
+- creates a GitHub Action to test as part of the CI/CD process,
+- providers Rake/Thor task(s) to run the tests locally.
+
+<!-- This is an optional element. Feel free to remove. -->
+## Decision Drivers
+
+* It's a legal requirement to ensure that the websites and mobile applications we produce are accessible. This is done by showing compliance to the 'AA' standard of the WCAG 2.1 guidelines.
+
+## Considered Options
+
+* [Pa11y](https://pa11y.org)
+* [aXe](https://www.deque.com/axe/)
+* [Google Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/)
+* [HTML_CodeSniffer](https://squizlabs.github.io/HTML_CodeSniffer/)
+* [SortSite](https://www.powermapper.com/products/sortsite/)
+* [WAVE](https://wave.webaim.org)
+* [ANDI](https://www.ssa.gov/accessibility/andi/help/howtouse.html)
+
+## Decision Outcome
+
+Chosen option: "Pa11y" because:
+* it is a tool that we have already used as part of a GitHub workflow,
+* we can run it twice to measure AA and AAA compliance,
+* it runs [HTML_CodeSniffer](https://squizlabs.github.io/HTML_CodeSniffer/), [aXe](https://www.deque.com/axe/) or both as "test runners"
+
+## More Information
+
+GOV.UK Service Manual:
+- [Making your service accessible: an introduction](https://www.gov.uk/service-manual/helping-people-to-use-your-service/making-your-service-accessible-an-introduction)
+- [Understanding WCAG 2.1](https://www.gov.uk/service-manual/helping-people-to-use-your-service/understanding-wcag)
+- [Getting an accessibility audit](https://www.gov.uk/service-manual/helping-people-to-use-your-service/getting-an-accessibility-audit)
+- [Testing for accessibility](https://www.gov.uk/service-manual/helping-people-to-use-your-service/testing-for-accessibility#automated-testing)
+
+Potential Auditors:
+- [Digital Accessibility Centre](https://digitalaccessibilitycentre.org/auditandaccreditation.html)
+- [Accessibility Services](https://www.accessibility-services.co.uk/services/digital-accessibility/digital-accessibility-assessment/)

data/docs/decisions/0007-test-for-insensitive-and-inconsiderate-writing.md

@@ -0,0 +1,32 @@
+---
+# Configuration for the Jekyll template "Just the Docs"
+nav_order: 7
+parent: Decision Records
+
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+date: 2023-03-21
+---
+# Test for insensitive and inconsiderate writing
+
+## Context and Problem Statement
+
+Given that checking insensitive and inconsiderate writing can be automated, should we test for it?
+
+## Considered Options
+
+* [alex](https://alexjs.com) helps you find gender favouring, polarising, race related, religion inconsiderate, or other unequal phrasing.
+* Manually reviewing documentation.
+
+## Decision Outcome
+
+Chosen option: "alex", because
+* it gives us an automated way of checking for insensitive and inconsiderate writing.
+
+### Consequences
+
+* Good, because it raises awareness of inclusive communication within teams. As the project README says, "An error from alex can be an invitation to learn more".
+
+## More Information
+
+Alex provides a list of [further reading](https://github.com/get-alex/alex#further-reading).

data/docs/decisions/0008-software-as-a-service-saas-web-analytics-solution.md

@@ -0,0 +1,30 @@
+---
+# Configuration for the Jekyll template "Just the Docs"
+nav_order: 8
+parent: Decision Records
+title: SaaS Web Analytics Solution
+
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+date: 2023-04-13
+deciders: Rosemarie Gant, Tim Gentry
+---
+# Software-as-a-Service (SaaS) Web Analytics Solution
+
+## Context and Problem Statement
+
+When we are in the position to use a hosted web analytics solution, we should use one, but which one should we use?
+
+## Considered Options
+
+<!--alex ignore simple -->
+* [Simple Analytics](https://www.simpleanalytics.com) The privacy-first Google Analytics alternative.
+* [Cabin](https://withcabin.com) is a privacy-first, carbon conscious web analytics solution.
+* [Google Analytics](https://marketingplatform.google.com/about/analytics/) gives you the tools, free of charge, to understand the customer journey and improve marketing ROI.
+
+## Decision Outcome
+
+Chosen option: "Cabin", because:
+* it is a cookie free solution, that does not track or gather metrics on visitors,
+* it offers good value for money,
+* it is hosted sustainably.

data/docs/decisions/0009-pull-request-guidlines-and-template.md

@@ -0,0 +1,31 @@
+---
+# Configuration for the Jekyll template "Just the Docs"
+nav_order: 9
+parent: Decision Records
+
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+date: 2023-05-24
+---
+# Pull Request guidelines and template
+
+## Context and Problem Statement
+
+The structure of a Pull Request (PR) can take many forms, making it difficult to understand at a glance the what, why and how of a PR. Which form should we choose?
+
+## Considered Options
+
+* Formless – No conventions for PR format and structure
+* [What? Why? How? Testing? Screenshots (optional) Anything Else?](https://www.pullrequest.com/blog/writing-a-great-pull-request-description/)
+* [GitHub pull request template](https://axolo.co/blog/p/part-3-github-pull-request-template) examples
+* [How to Write a Proper Description for a Pull Request](https://maddevs.io/blog/how-to-make-a-proper-description-for-a-pull-request/)
+
+## Decision Outcome
+
+Chosen option: "What? Why? How? Testing? Screenshots (optional) Anything Else?", because clear, well-structured pull request descriptions help reviewers understand the context, changes, and testing done, making code reviews faster and more effective..
+
+Although not a template format, we should also include GitHub's communication guidelines in [How to write the perfect pull request](https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/).
+
+## More Information
+
+Whichever format is chosen, we should create an initialiser to add the GitHub [PR template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) to a project.

data/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/docs/decisions/adr-template.md

@@ -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: {YYYY-MM-DD when the decision was last updated}
+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}
+---
+# {short title of solved problem and solution}
+
+## 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/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/docs/index.md

@@ -0,0 +1,33 @@
+---
+# Feel free to add content and custom Front Matter to this file.
+# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults
+
+layout: home
+nav_order: 1
+permalink: /
+title: Home
+---
+
+# The HDI Way of Working
+
+## Introduction
+
+This evolving framework will describe a consistent, high-quality approach to Data and Software Engineering at Health Data Insight.
+
+It is an opinionated approach intending to support rapid development, across numerous projects, by a fungible workforce who can swap between assignments with the minimum friction.
+
+It builds on the [twelve-factor app](https://12factor.net) methodology and is intended to be compatible with the [NHS Digital Software Engineering Quality Framework](https://github.com/NHSDigital/software-engineering-quality-framework) and other frameworks like [the GDS Way](https://gds-way.cloudapps.digital).
+
+The most significant difference is that we will be opinionated and make technological and process choices. Everyone is encouraged to discuss and submit Pull Requests (PRs) if they want changes to the choices made, but by making those choices, we can automate many tedious background tasks that are currently manual.
+
+## Installation
+
+HDI Way of Working can be installed at the command line on any machine with Ruby installed.
+
+If you have a Ruby based project, using Bundler to manage dependencies, then install the gem and add to the application's Gemfile by executing:
+
+    bundle add way_of_working
+
+Otherwise install the gem by executing:
+
+    gem install way_of_working

data/docs/pa11y.json

@@ -0,0 +1,9 @@
+{
+  "chromeLaunchConfig": {
+      "args": [
+          "--no-sandbox",
+          "--disable-setuid-sandbox",
+          "--disable-dev-shm-usage"
+      ]
+  }
+}

data/docs/way_of_working/accessibility-testing.md

@@ -0,0 +1,29 @@
+---
+layout: page
+---
+
+# Accessibility Testing
+
+"Accessibility" is sometimes shortened to "a11y", with 11 (characters) replacing "ccessibilit".
+
+Automated accessibility testing tools are designed to identify potential accessibility issues on a website or application, such as missing alternative text for images or incorrect heading structure.
+
+<!--alex disable easy-->
+However, automated testing tools have some limitations and cannot catch all accessibility issues. Some accessibility issues require human interpretation and judgment, such as whether a website's language is clear and easy to understand.
+
+Additionally, automated testing tools can generate false positives or false negatives. False positives occur when the tool reports an issue that is not a problem, and false negatives occur when the tool fails to detect an issue that is a problem. For example, an automated testing tool may flag an image as missing alternative text when it has descriptive text nearby or fail to detect an issue with a complex form that requires user testing to identify.
+
+Human auditors can provide valuable insight and identify issues that automated tools may miss. They can also verify and validate the results generated by the automated testing tools. By combining automated testing with human auditing, website owners can ensure their website is accessible to the broadest possible audience, including people with disabilities.
+
+Despite the limitations, automated testing can catch basic accessibility issues at an early stage of development, enabling human auditors to focus on more significant problems. We use [Pa11y](https://pa11y.org).
+
+## Usage
+
+### Manual Approach
+
+Follow the [pa11y instructions](https://github.com/pa11y/pa11y#command-line-interface) to install and run pa11y locally.
+
+### Automatic Approach
+
+There is currently no tooling within the Way of Working to use pa11y.
+

data/docs/way_of_working/changelog.md

@@ -0,0 +1,58 @@
+---
+layout: page
+---
+
+# Changelog
+
+![Keep a Changelog v1.1.0 badge][changelog-badge]
+
+We use [keep a changelog](https://keepachangelog.com/en/1.1.0/) version 1.1.0. It has a well-defined structure that makes it an accessible format for people and tooling.
+
+To quote from their website:
+
+> Guiding Principles:
+> * Changelogs are for humans, not machines.
+> * There should be an entry for every single version.
+> * The same types of changes should be grouped.
+> * Versions and sections should be linkable.
+> * The latest version comes first.
+> * The release date of each version is displayed.
+> * Mention whether you follow Semantic Versioning.
+
+Grouping changes into a clear set of change types:
+
+> * `Added` for new features.
+> * `Changed` for changes in existing functionality.
+> * `Deprecated` for soon-to-be removed features.
+> * `Removed` for now removed features.
+> * `Fixed` for any bug fixes.
+> * `Security` in case of vulnerabilities.
+
+{: .important }
+Unlike automatic tools like github-changelog-generator, keep a changelog is a human-written, plain English summary of changes. It is **not** a commit log dump; please do not use it as such.
+
+We recommend that you and your team update the changelog within your Pull Requests, which avoids the need to add to the changelog much later, at release. Please read the [keep a changelog](https://keepachangelog.com/en/1.1.0/) website. It's a single page with lots of important advice about the benefits and dangers of an incomplete changelog, but as it says in the FAQs, you can always revisit and improve a changelog over time.
+
+The Way of Working command line tool scaffolds a new changelog on new and longstanding projects.
+
+On longstanding git-based projects, it reads the release tags and scaffolds a changelog with the expected changes of a [semantically versioned](https://semver.org) project. So, for example, a patch or minor version change won't contain a scaffolded `Removed` section.
+
+Please use the links within the scaffolded changelog to view all the commits between releases to document historical changes.
+
+{: .note }
+There is no tooling to support the continued scaffolding of new releases to an existing changelog because the expectation is that you are updating it day-to-day.
+
+{: .highlight }
+We want to provide tooling (including a Rails helper method) that reads the changelog and converts it to HTML for inclusion within the project website. Developers could also give it a last-logged-in date to highlight all the changes since a user last logged in. If you would like to contribute to this functionality, let us know.
+
+## Usage
+
+### Adding a changelog to your project
+
+To add a [keep a changelog v1.1.0](https://keepachangelog.com/en/1.1.0/) changelog to your project, use the following at the command line:
+
+```bash
+way_of_working init changelog
+```
+
+[changelog-badge]: https://img.shields.io/badge/changelog-Keep%20a%20Changelog%20v1.1.0-%23E05735

data/docs/way_of_working/code-linting/index.md

@@ -0,0 +1,39 @@
+---
+has_children: true
+layout: page
+---
+
+# Code Linting
+
+We use [MegaLinter](https://megalinter.io/) for the majority of our code lining, currently with separate Ruby testing with RuboCop.
+
+Code linters like MegaLinter benefit developers and teams because they help improve code quality, reduce errors and inconsistencies, and streamline development. Linters analyze source code for common issues, such as syntax errors, undefined variables, and unused code, and provide suggestions and feedback for improvement.
+
+Using a linter like MegaLinter, developers can catch and fix errors early in the development process, saving time and effort in the long run.
+The linter also provides consistency in the codebase, helping to prevent errors caused by different team members using different styles or approaches, which can be especially valuable for large projects with many contributors or where you want staff to be able to switch between projects more efficiently.
+
+MegaLinter is a particularly powerful linter because it supports multiple programming languages, making it a one-stop shop for developers working on projects with various languages.
+
+{: .note }
+We have chosen not to use the version of [RuboCop](https://rubocop.org) packaged in MegaLinter because it can't support our use of Minitest and Rails "cops". But by using our CLI command to run linting, as documented below, both RuboCop and MegaLinter will be executed against your code.
+
+When you add the Way of Working linter to your project, it will copy our per-language organisational code styles (where they differ from defaults) into `.github/linters` and will copy the GitHub Actions workflow files into `.github/workflow`, so that linting automatically runs when you commit to GitHub.
+
+If you add the Way of Working linter to your Xcode project, it will automatically add a Swiftlint build phase to the project config file.
+
+{: .important }
+If you disagree with any of the linters or linting styles that they apply, please fork the repository and create a pull request with your desired changes. The current coding standards are only intended as a starting point. A Full list of the linters we are currently using can be found [here](linters.md).
+
+## Usage
+
+To add [MegaLinter](https://megalinter.io/) and [RuboCop](https://rubocop.org) to your project, run the following at the command line:
+
+    way_of_working init code_linting
+
+to run MegaLinter in your project, run:
+
+    way_of_working exec code_linting
+
+to document your use of MegaLinter in your project, run:
+
+    way_of_working exec document