Vale for prose checking (#135)

## Description [Vale](https://vale.sh/) is a tool for performing a certain set of style checks, which this PR introduces for markdown files only. Vale can scan code comments, but as an initial validation we should limit the scope. WIP for the moment while I sort out github action integration. ## Context We want to be sure that our documentation is consistent and readable. ## Type of changes - [ ] Refactoring (non-breaking change) - [x] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would change existing functionality) - [ ] Bug fix (non-breaking change which fixes an issue) ## Checklist  - [x] I am familiar with the [contributing guidelines](../docs/CONTRIBUTING.md) - [x] I have followed the code style of the project - [ ] I have added tests to cover my changes - [x] I have updated the documentation accordingly - [ ] This PR is a result of pair or mob programming --- ## Sensitive Information Declaration To ensure the utmost confidentiality and protect your and others privacy, we kindly ask you to NOT including [PII (Personal Identifiable Information) / PID (Personal Identifiable Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public) or any other sensitive data in this PR (Pull Request) and the codebase changes. We will remove any PR that do contain any sensitive information. We really appreciate your cooperation in this matter. - [x] I confirm that neither PII/PID nor sensitive data are included in this PR and the codebase changes. --------- Co-authored-by: Dan Stefaniuk <[email protected]>
nhs-england-tools · Nov 22, 2023 · 533f4cf · 533f4cf
1 parent c869280
commit 533f4cf
Show file tree

Hide file tree

Showing 22 changed files with 203 additions and 63 deletions.
diff --git a/.github/SECURITY.md b/.github/SECURITY.md
@@ -32,4 +32,4 @@ You can report vulnerabilities here: [https://www.ncsc.gov.uk/information/vulner
 
 ## General Security Enquiries
 
-If you have general enquiries regarding our cyber security, please reach out to us at [[email protected]]([email protected])
+If you have general enquiries regarding our cybersecurity, please reach out to us at [[email protected]]([email protected])
diff --git a/.github/actions/lint-prose/action.yaml b/.github/actions/lint-prose/action.yaml
@@ -0,0 +1,9 @@
+name: "Check English usage"
+description: "Check English usage"
+runs:
+  using: "composite"
+  steps:
+    - name: "Check English usage"
+      shell: bash
+      run: |
+        check=branch ./scripts/githooks/check-english-usage.sh
diff --git a/.github/workflows/stage-1-commit.yaml b/.github/workflows/stage-1-commit.yaml
@@ -66,6 +66,17 @@ jobs:
           fetch-depth: 0 # Full history is needed to compare branches
       - name: "Check markdown format"
         uses: ./.github/actions/check-markdown-format
+  lint-prose:
+    name: "Check English usage"
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history is needed to compare branches
+      - name: "Check English usage"
+        uses: ./.github/actions/lint-prose
   lint-terraform:
     name: "Lint Terraform"
     runs-on: ubuntu-latest

diff --git a/README.md b/README.md
@@ -45,15 +45,15 @@ cd nhs-england-tools/repository-template
 
 The following software packages, or their equivalents, are expected to be installed and configured:
 
-- [docker](https://www.docker.com/) container runtime or a compatible tool, e.g. [podman](https://podman.io/),
+- [Docker](https://www.docker.com/) container runtime or a compatible tool, e.g. [Podman](https://podman.io/),
 - [asdf](https://asdf-vm.com/) version manager,
 - [GNU make](https://www.gnu.org/software/make/) 3.82 or later,
 - [GNU coreutils](https://www.gnu.org/software/coreutils/) and [GNU binutils](https://www.gnu.org/software/binutils/) may be required to build dependencies like Python, which may need to be compiled during installation. For macOS users, this has been scripted and automated by the `dotfiles` project; please see this [script](https://github.com/nhs-england-tools/dotfiles/blob/main/assets/20-install-base-packages.macos.sh) for details,
 - [Python](https://www.python.org/) required to run Git hooks,
-- [jq](https://jqlang.github.io/jq/) a lightweight and flexible command-line JSON processor.
+- [`jq`](https://jqlang.github.io/jq/) a lightweight and flexible command-line JSON processor.
 
 > [!NOTE]<br>
-> The version of GNU make available by default on macOS is earlier than 3.82. You will need to upgrade it or certain `make` tasks will fail. On macOS, you will need [homebrew](https://brew.sh/) installed, then to install `make`, like so:
+> The version of GNU make available by default on macOS is earlier than 3.82. You will need to upgrade it or certain `make` tasks will fail. On macOS, you will need [Homebrew](https://brew.sh/) installed, then to install `make`, like so:
 >
 > ```shell
 > brew install make

diff --git a/.../ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md b/.../ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md
@@ -106,7 +106,7 @@ This option is an extension built upon option 2a.
 - Pros
   - Usage of a GitHub native functionality
 - Cons
-  - Reliance on the GitHub DSL (coding in yaml) may lead to less portable solution
+  - Reliance on the GitHub DSL (coding in YAML) may lead to less portable solution
   - Implementation of the functionality has to be duplicated for the git hook
 
 ### Outcome

diff --git a/docs/adr/ADR-002_Scan_repository_for_hardcoded_secrets.md b/docs/adr/ADR-002_Scan_repository_for_hardcoded_secrets.md
@@ -1,4 +1,4 @@
-# ADR-002: Scan repository for hardcoded secrets
+# ADR-002: Scan repository for hard-coded secrets
 
 >|              |                                                               |
 >| ------------ | ------------------------------------------------------------- |
@@ -10,7 +10,7 @@
 
 ---
 
-- [ADR-002: Scan repository for hardcoded secrets](#adr-002-scan-repository-for-hardcoded-secrets)
+- [ADR-002: Scan repository for hard-coded secrets](#adr-002-scan-repository-for-hard-coded-secrets)
   - [Context](#context)
   - [Decision](#decision)
     - [Assumptions](#assumptions)
@@ -42,7 +42,7 @@ Within NHS England, we are observing an adoption of the `gitleaks` tool, which i
 
 There are three options presented in this decision record.
 
-1. [git-secrets](https://github.com/awslabs/git-secrets)
+1. [Git-secrets](https://github.com/awslabs/git-secrets)
 
    - Repository metadata
      - Contributions
@@ -66,9 +66,9 @@ There are three options presented in this decision record.
    - Cons
      - Rules and exclusion patterns are not easy to manage as no comments or metadata are allowed in the definition
      - No pre-backed Docker image
-     - Activity of the repo has dropped (last commit a while ago)
+     - Activity of the repository has dropped (last commit a while ago)
 
-2. [trufflehog](https://github.com/trufflesecurity/trufflehog)
+2. [Trufflehog](https://github.com/trufflesecurity/trufflehog)
 
    - Repository metadata
      - Contributions
@@ -93,7 +93,7 @@ There are three options presented in this decision record.
    - Cons
      - [AGPL-3.0](https://choosealicense.com/licenses/agpl-3.0/) licence comes with conditions
 
-3. [gitleaks](https://github.com/gitleaks/gitleaks)
+3. [Gitleaks](https://github.com/gitleaks/gitleaks)
 
    - Repository metadata
 

diff --git a/docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md b/docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md
@@ -55,7 +55,7 @@ Requirements:
 
 ### Assumptions
 
-Summarise the underlying assumptions in the environment in which you make the decision. This could be related to technology changes, forecast of the monetary and non-monetary costs, further delivery commitments, impactful external drivers etc., and any known unknowns that translate to risks.
+Summarise the underlying assumptions in the environment in which you make the decision. This could be related to technology changes, forecast of the monetary and non-monetary costs, further delivery commitments, impact from external drivers etc., and any known unknowns that translate to risks.
 
 ### Drivers
 

diff --git a/docs/adr/ADR-nnn_Any_Decision_Record_Template.md b/docs/adr/ADR-nnn_Any_Decision_Record_Template.md
@@ -32,7 +32,7 @@ Describe the context and the problem statement. Is there a relationship to other
 
 ### Assumptions
 
-Summarise the underlying assumptions in the environment in which you make the decision. This could be related to technology changes, forecast of the monetary and non-monetary costs, further delivery commitments, impactful external drivers etc., and any known unknowns that translate to risks.
+Summarise the underlying assumptions in the environment in which you make the decision. This could be related to technology changes, forecast of the monetary and non-monetary costs, further delivery commitments, impact from external drivers etc., and any known unknowns that translate to risks.
 
 ### Drivers
 

diff --git a/docs/adr/assets/ADR-003/examples/nodejs/README.md b/docs/adr/assets/ADR-003/examples/nodejs/README.md
@@ -26,4 +26,4 @@ $ yarn start
       ...
 ```
 
-See the [example (main.ts)](./main.ts) implementation. This script has been written to illustrate the concept in a clear and simple way. It is not a production ready code.
+See the [example (`main.ts`)](./main.ts) implementation. This script has been written to illustrate the concept in a clear and simple way. It is not a production ready code.
diff --git a/docs/developer-guides/Bash_and_Make.md b/docs/developer-guides/Bash_and_Make.md
@@ -140,7 +140,7 @@ VERBOSE=1 scripts/shellscript-linter.sh
 
 ### Scripts
 
-Most scripts provided with this repository template can utilise tools installed on your `PATH` if they are available or run them from within a Docker container. To force a script to use Docker, the `FORCE_USE_DOCKER` variable is provided. This feature increases configurability of the development environment, allowing you to use custom tooling by default if present on the command-line path. Here is an example of how to use it:
+Most scripts provided with this repository template can use tools installed on your `PATH` if they are available or run them from within a Docker container. To force a script to use Docker, the `FORCE_USE_DOCKER` variable is provided. This feature allows you to use custom tooling if it is present on the command-line path. Here is how to use it:
 
 ```shell
 FORCE_USE_DOCKER=1 scripts/shellscript-linter.sh

diff --git a/docs/developer-guides/Scripting_Docker.md b/docs/developer-guides/Scripting_Docker.md
@@ -40,29 +40,29 @@ Here are some key features built into this repository's Docker module:
 - Consolidates image versions in a unified `.tool-versions` file for easier dependency management
 - Optimises the build process specifically for the `amd64` architecture for consistency
 - Applies automatic image versioning according to a predefined pattern for artefact publishing and deployment
-- Incorporates metadata through Dockerfile labels for enhanced documentation and to conform to standards
-- Integrates a linting routine to ensure Dockerfile code quality
+- Incorporates metadata through `Dockerfile` labels for enhanced documentation and to conform to standards
+- Integrates a linting routine to ensure `Dockerfile` code quality
 - Includes an automated test suite to validate Docker scripts
 - Provides a ready-to-run example to demonstrate the module's functionality
 - Incorporates a best practice guide
 
 ## Key files
 
 - Scripts
-  - [docker.lib.sh](../../scripts/docker/docker.lib.sh): A library code loaded by custom make targets and CLI scripts
-  - [docker.mk](../../scripts/docker/docker.mk): Customised implementation of the Docker routines loaded by the `scripts/init.mk` file
-  - [dgoss.sh](../../scripts/docker/dgoss.sh): Docker image spec test framework
-  - [dockerfile-linter.sh](../../scripts/docker/dockerfile-linter.sh): Dockerfile linter
+  - [`docker.lib.sh`](../../scripts/docker/docker.lib.sh): A library code loaded by custom make targets and CLI scripts
+  - [`docker.mk`](../../scripts/docker/docker.mk): Customised implementation of the Docker routines loaded by the `scripts/init.mk` file
+  - [`dgoss.sh`](../../scripts/docker/dgoss.sh): Docker image spec test framework
+  - [`dockerfile-linter.sh`](../../scripts/docker/dockerfile-linter.sh): `Dockerfile` linter
 - Configuration
-  - [.tool-versions](../../.tool-versions): Stores Docker image versions
-  - [hadolint.yaml](../../scripts/config/hadolint.yaml): Dockerfile linter configuration file
-  - [Dockerfile.metadata](../../scripts/docker/Dockerfile.metadata): Labels added to image definition as specified by the spec
+  - [`.tool-versions`](../../.tool-versions): Stores Docker image versions
+  - [`hadolint.yaml`](../../scripts/config/hadolint.yaml): `Dockerfile` linter configuration file
+  - [`Dockerfile.metadata`](../../scripts/docker/Dockerfile.metadata): Labels added to image definition as specified by the spec
 - Test suite
-  - [docker.test.sh](../../scripts/docker/tests/docker.test.sh): Main file containing all the tests
-  - [Dockerfile](../../scripts/docker/tests/Dockerfile): Image definition for the test suite
-  - [VERSION](../../scripts/docker/tests/VERSION): Version patterns for the test suite
+  - [`docker.test.sh`](../../scripts/docker/tests/docker.test.sh): Main file containing all the tests
+  - [`Dockerfile`](../../scripts/docker/tests/Dockerfile): Image definition for the test suite
+  - [`VERSION`](../../scripts/docker/tests/VERSION): Version patterns for the test suite
 - Usage example
-  - Python-based example [hello_world](../../scripts/docker/examples/python) app showing a multi-staged build
+  - Python-based example [`hello_world`](../../scripts/docker/examples/python) app showing a multi-staged build
   - A set of [make targets](https://github.com/nhs-england-tools/repository-template/blob/main/scripts/docker/docker.mk#L18) to run the example
 
 ## Usage
@@ -113,7 +113,7 @@ Here is a step-by-step guide:
    FROM cypress/browsers:latest
    ```
 
-2. Add the following entry to the `.tool-versions` file. This will be used to replace the `latest` version placeholder in the Dockerfile.
+2. Add the following entry to the `.tool-versions` file. This will be used to replace the `latest` version placeholder in the `Dockerfile`.
 
    ```text
    # docker/cypress/browsers node-20.5.0-chrome-114.0.5735.133-1-ff-114.0.2-edge-114.0.1823.51-1@sha256:8b899d0292e700c80629d13a98ae309295e719f5b4f9aa50a98c6cdd2b6c5215

diff --git a/docs/developer-guides/Scripting_Terraform.md b/docs/developer-guides/Scripting_Terraform.md
@@ -20,9 +20,9 @@ Terraform is an open-source infrastructure as code (IaC) tool. It allows you to
 Some advantages of using Terraform are as outlined below:
 
 - **Declarative configuration**: Terraform enables the precise definition of the desired state of infrastructure, streamlining its creation through a readable and understandable codebase.
-- **Version control**: The infrastructure code may be subject to version control, thereby providing an auditable record of environmental changes.
+- **Version control**: The infrastructure code may be subject to version control, thereby providing an audit trail of environmental changes.
 - **Modularisation and reusability**: Terraform facilitates the packaging of infrastructure into modular components, enhancing both reusability and ease of sharing across organisational teams.
-- **State management**: Terraform's state management capabilities ensure an accurate representation of real-world resources, enabling features such as resource dependencies and idempotency.
+- **State management**: Terraform's state management capabilities ensure an accurate representation of real-world resources, enabling features such as resource dependencies and idempotence.
 - **Collaboration and workflow**: The platform supports collaboration through features like remote backends and state locking, thereby fostering collective work on infrastructure projects.
 - **Community and ecosystem**: A robust community actively contributes to the Terraform ecosystem, providing a wealth of modules and examples that expedite infrastructure development.
 
@@ -46,16 +46,16 @@ Here are some key features built into this repository's Terraform module:
 ## Key files
 
 - Scripts
-  - [terraform.lib.sh](../../scripts/terraform/terraform.lib.sh) A library code loaded by custom make targets and CLI scripts
-  - [terraform.mk](../../scripts/terraform/terraform.mk): Customised implementation of the Terraform routines loaded by the `scripts/init.mk` file
-  - [terraform.sh](../../scripts/terraform/terraform.sh): Terraform command wrapper
+  - [`terraform.lib.sh`](../../scripts/terraform/terraform.lib.sh) A library code loaded by custom make targets and CLI scripts
+  - [`terraform.mk`](../../scripts/terraform/terraform.mk): Customised implementation of the Terraform routines loaded by the `scripts/init.mk` file
+  - [`terraform.sh`](../../scripts/terraform/terraform.sh): Terraform command wrapper
 - Configuration
-  - [.tool-versions](../../.tool-versions): Stores Terraform version to be used
+  - [`.tool-versions`](../../.tool-versions): Stores Terraform version to be used
 - Code quality gates
-  - [lint-terraform/action.yaml](../../.github/actions/lint-terraform/action.yaml): GitHub action
-  - [check-terraform-format.sh](../../scripts/githooks/check-terraform-format.sh): Git hook
+  - [`lint-terraform/action.yaml`](../../.github/actions/lint-terraform/action.yaml): GitHub action
+  - [`check-terraform-format.sh`](../../scripts/githooks/check-terraform-format.sh): Git hook
 - Usage example
-  - Declarative infrastructure definition example [terraform-state-aws-s3](../../scripts/terraform/examples/terraform-state-aws-s3) to store Terraform state
+  - Declarative infrastructure definition example [`terraform-state-aws-s3`](../../scripts/terraform/examples/terraform-state-aws-s3) to store Terraform state
   - A set of [make targets](https://github.com/nhs-england-tools/repository-template/blob/main/scripts/terraform/terraform.mk#L44) to run the example
 
 ## Usage

diff --git a/docs/user-guides/Run_Git_hooks_on_commit.md b/docs/user-guides/Run_Git_hooks_on_commit.md
@@ -14,13 +14,13 @@ The [pre-commit](https://pre-commit.com/) framework is a powerful tool for manag
 ## Key files
 
 - Scripts
-  - [check-file-format.sh](../../scripts/githooks/check-file-format.sh)
-  - [check-markdown-format.sh](../../scripts/githooks/check-markdown-format.sh)
-  - [check-terraform-format.sh](../../scripts/githooks/check-terraform-format.sh)
-  - [scan-secrets.sh](../../scripts/githooks/scan-secrets.sh)
+  - [`check-file-format.sh`](../../scripts/githooks/check-file-format.sh)
+  - [`check-markdown-format.sh`](../../scripts/githooks/check-markdown-format.sh)
+  - [`check-terraform-format.sh`](../../scripts/githooks/check-terraform-format.sh)
+  - [`scan-secrets.sh`](../../scripts/githooks/scan-secrets.sh)
 - Configuration
-  - [pre-commit.yaml](../../scripts/config/pre-commit.yaml)
-  - [init.mk](../../scripts/init.mk): make targets
+  - [`pre-commit.yaml`](../../scripts/config/pre-commit.yaml)
+  - [`init.mk`](../../scripts/init.mk): make targets
 
 ## Testing
Original file line number	Diff line number	Diff line change
Expand Up		@@ -32,4 +32,4 @@ You can report vulnerabilities here: [https://www.ncsc.gov.uk/information/vulner

		## General Security Enquiries

		If you have general enquiries regarding our cyber security, please reach out to us at [[email protected]]([email protected])
		If you have general enquiries regarding our cybersecurity, please reach out to us at [[email protected]]([email protected])
-Original file line number
+Diff line change
@@ Expand Up / @@ -26,4 +26,4 @@ $ yarn start @@
           ...
     ```
-    See the [example (main.ts)](./main.ts) implementation. This script has been written to illustrate the concept in a clear and simple way. It is not a production ready code.
+    See the [example (`main.ts`)](./main.ts) implementation. This script has been written to illustrate the concept in a clear and simple way. It is not a production ready code.