From de3fb39a864d6498dd2a966b2fd9c1ee3098e61e Mon Sep 17 00:00:00 2001 From: regularfry Date: Thu, 12 Oct 2023 12:07:08 +0100 Subject: [PATCH] Remove commas after the word "please" A comma before "please" at the end of a sentence is often necessary, but a comma after "please" rarely is. The exception would be in sentences that have an interposed "please" somewhere in the middle, like "Make sure, please, to switch off the nuclear reactor before attempting to clean the reaction vessel." But I don't think we've got any sentences like that hanging around. --- ...nd_GitHub_action_to_check_the_editorconfig_compliance.md | 2 +- ...ptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md | 2 +- docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md | 2 +- docs/adr/ADR-nnn_Any_Decision_Record_Template.md | 2 +- docs/developer-guides/Bash_and_Make.md | 2 +- docs/user-guides/Perform_static_analysis.md | 2 +- docs/user-guides/Scan_dependencies.md | 2 +- docs/user-guides/Sign_Git_commits.md | 2 +- scripts/config/sonar-scanner.properties | 2 +- scripts/docker/dgoss.sh | 2 +- scripts/docker/docker.lib.sh | 2 +- scripts/docker/docker.mk | 4 ++-- scripts/docker/dockerfile-linter.sh | 2 +- scripts/docker/tests/docker.test.sh | 2 +- scripts/githooks/check-file-format.sh | 2 +- scripts/githooks/check-markdown-format.sh | 2 +- scripts/githooks/check-terraform-format.sh | 2 +- scripts/init.mk | 4 ++-- scripts/shellscript-linter.sh | 2 +- scripts/terraform/terraform.lib.sh | 2 +- scripts/terraform/terraform.mk | 6 +++--- scripts/terraform/terraform.sh | 2 +- scripts/tests/test.mk | 2 +- 23 files changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/adr/ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md b/docs/adr/ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md index 6a8a51c9..35f82b7c 100644 --- a/docs/adr/ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md +++ b/docs/adr/ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md @@ -136,7 +136,7 @@ Both, the git hook and the GitHub Action should be executed automatically as par ## Notes -There is an emerging practice to use projects like [act](https://github.com/nektos/act) to make GitHub Actions even more portable. ~~The recommendation is for this tool to be assessed at further stages of the [nhs-england-tools/repository-template](https://github.com/nhs-england-tools/repository-template) project implementation, in the context of this decision record.~~ Update: Please, see the [Test GitHub Actions locally](../user-guides/Test_GitHub_Actions_locally.md) user guide. +There is an emerging practice to use projects like [act](https://github.com/nektos/act) to make GitHub Actions even more portable. ~~The recommendation is for this tool to be assessed at further stages of the [nhs-england-tools/repository-template](https://github.com/nhs-england-tools/repository-template) project implementation, in the context of this decision record.~~ Update: Please see the [Test GitHub Actions locally](../user-guides/Test_GitHub_Actions_locally.md) user guide. ## Actions diff --git a/docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md b/docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md index 26aef0cf..cd82a32c 100644 --- a/docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md +++ b/docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md @@ -198,7 +198,7 @@ C4Context } ``` -Please, see the above being implemented for the _update from template_ capability: +Please see the above being implemented for the _update from template_ capability: - [Repository and GitHub App (runner)](https://github.com/nhs-england-tools/update-from-template-app) for the "Update from Template" app. The runner is built on a GitHub Action but it can be a serverless workload or self-hosted compute - [GitHub account (bot)](https://github.com/update-from-template-app) linked to an `nhs.net` email address, but not part of any GitHub organisation diff --git a/docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md b/docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md index 81f5c54a..1201690c 100644 --- a/docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md +++ b/docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md @@ -26,7 +26,7 @@ ## Context -Describe the context and the problem statement. Is there a relationship to other decisions previously made? Are there any dependencies and/or constraints within which the decision will be made? Do these need to be reviewed or validated? Please, note that environmental limitations or restrictions such as accepted technology standards, commonly recognised and used patterns, engineering and architecture principles, organisation policies, governance and so on, may as an effect narrow down the choices. This should also be explicitly documented, as this is a point-in-time decision with the intention of being able to articulate it clearly and justify it later. +Describe the context and the problem statement. Is there a relationship to other decisions previously made? Are there any dependencies and/or constraints within which the decision will be made? Do these need to be reviewed or validated? Please note that environmental limitations or restrictions such as accepted technology standards, commonly recognised and used patterns, engineering and architecture principles, organisation policies, governance and so on, may as an effect narrow down the choices. This should also be explicitly documented, as this is a point-in-time decision with the intention of being able to articulate it clearly and justify it later. Requirements: diff --git a/docs/adr/ADR-nnn_Any_Decision_Record_Template.md b/docs/adr/ADR-nnn_Any_Decision_Record_Template.md index 6d84ce0d..74993e87 100644 --- a/docs/adr/ADR-nnn_Any_Decision_Record_Template.md +++ b/docs/adr/ADR-nnn_Any_Decision_Record_Template.md @@ -26,7 +26,7 @@ ## Context -Describe the context and the problem statement. Is there a relationship to other decisions previously made? Are there any dependencies and/or constraints within which the decision will be made? Do these need to be reviewed or validated? Please, note that environmental limitations or restrictions such as accepted technology standards, commonly recognised and used patterns, engineering and architecture principles, organisation policies, governance and so on, may as an effect narrow down the choices. This should also be explicitly documented, as this is a point-in-time decision with the intention of being able to articulate it clearly and justify it later. +Describe the context and the problem statement. Is there a relationship to other decisions previously made? Are there any dependencies and/or constraints within which the decision will be made? Do these need to be reviewed or validated? Please note that environmental limitations or restrictions such as accepted technology standards, commonly recognised and used patterns, engineering and architecture principles, organisation policies, governance and so on, may as an effect narrow down the choices. This should also be explicitly documented, as this is a point-in-time decision with the intention of being able to articulate it clearly and justify it later. ## Decision diff --git a/docs/developer-guides/Bash_and_Make.md b/docs/developer-guides/Bash_and_Make.md index 95a79066..3bcd7753 100644 --- a/docs/developer-guides/Bash_and_Make.md +++ b/docs/developer-guides/Bash_and_Make.md @@ -19,7 +19,7 @@ some-target: # Target description - mandatory: foo=[description]; optional: baz= - `some-target`: This is the name of the target you would specify when you want to run this particular target. Use the kebab-case naming convention and prefix with an underscore `_` to mark it as a "private" target. The first part of the name is used for grouping, e.g. `docker-*` or `terraform-*`. - `Target Description`: Provided directly after the target name as a single line, so be concise. -- `mandatory` parameters: Parameters that must be provided when invoking the target. Each parameter has its own description. Please, follow the specified format as it is used by `make help`. +- `mandatory` parameters: Parameters that must be provided when invoking the target. Each parameter has its own description. Please follow the specified format as it is used by `make help`. - `optional` parameters: Parameters that are not required when invoking the target. They may have a default value. Each parameter has its own description. - `@Category` label: Used for grouping by the `make help` command. - `Recipe implementation`: This section defines the actual commands or steps the target will execute. **Do not exceed 5 lines of effective code**. For more complex operations, use a shell script. Refer to the `docker-build` implementation in the [docker.mk](../../scripts/docker/docker.mk) file. More complex operations are implemented in the [docker.sh](../../scripts/docker/docker.lib.sh) script for readability and simplicity. diff --git a/docs/user-guides/Perform_static_analysis.md b/docs/user-guides/Perform_static_analysis.md index 284b6717..22447b93 100644 --- a/docs/user-guides/Perform_static_analysis.md +++ b/docs/user-guides/Perform_static_analysis.md @@ -31,7 +31,7 @@ Static code analysis is an essential part of modern software development. It pro - Add `SONAR_ORGANISATION_KEY` variable (not a secret) - Add `SONAR_PROJECT_KEY` variable (not a secret) - Navigate to project `Administration > Analysis Method` and turn off the `Automatic Analysis` option -- Please, refrain from adding your repository to the GitHub SonarCloud App, as this app should not be used. Doing so will duplicate reports and initiate them outside the primary pipeline workflow +- Please refrain from adding your repository to the GitHub SonarCloud App, as this app should not be used. Doing so will duplicate reports and initiate them outside the primary pipeline workflow - Confirm that the _"Perform static analysis"_ GitHub action is part of your GitHub CI/CD workflow and enforces the _"Sonar Way"_ quality gates. You can find more information about this in the [NHSE Software Engineering Quality Framework](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/tools/sonarqube.md) ## Testing diff --git a/docs/user-guides/Scan_dependencies.md b/docs/user-guides/Scan_dependencies.md index 411d07c0..8872aeca 100644 --- a/docs/user-guides/Scan_dependencies.md +++ b/docs/user-guides/Scan_dependencies.md @@ -70,4 +70,4 @@ cat vulnerabilities-repository-reportc.json | jq - Easier investigation of CVEs found in the repository, eliminating dependence on a third party like GitHub - Enhanced portability and flexibility, allowing the scans to run in diverse environments - However, this approach should be periodically reviewed as there is an emerging practice to use projects like [act](https://github.com/nektos/act) ~~to make GitHub Actions portable~~. Update: Please, see the [Test GitHub Actions locally](../user-guides/Test_GitHub_Actions_locally.md) user guide. + However, this approach should be periodically reviewed as there is an emerging practice to use projects like [act](https://github.com/nektos/act) ~~to make GitHub Actions portable~~. Update: Please see the [Test GitHub Actions locally](../user-guides/Test_GitHub_Actions_locally.md) user guide. diff --git a/docs/user-guides/Sign_Git_commits.md b/docs/user-guides/Sign_Git_commits.md index 1ac28246..0e353c27 100644 --- a/docs/user-guides/Sign_Git_commits.md +++ b/docs/user-guides/Sign_Git_commits.md @@ -25,7 +25,7 @@ There are two ways to sign commits in GitHub, using a GPG or an SSH signature. D ### Generate GPG key -If you do not have it already generate a new pair of GPG keys. Please, change the passphrase (pleaseChooseYourKeyPassphrase) below and save it in your password manager. +If you do not have it already generate a new pair of GPG keys. Please change the passphrase (pleaseChooseYourKeyPassphrase) below and save it in your password manager. ```shell USER_NAME="Your Name" diff --git a/scripts/config/sonar-scanner.properties b/scripts/config/sonar-scanner.properties index 2ae21c73..147891dc 100644 --- a/scripts/config/sonar-scanner.properties +++ b/scripts/config/sonar-scanner.properties @@ -1,4 +1,4 @@ -# Please, DO NOT set the following properties `sonar.organization` and `sonar.projectKey` in this file. They must be stored as `SONAR_ORGANISATION_KEY` and `SONAR_PROJECT_KEY` GitHub secrets. +# Please DO NOT set the following properties `sonar.organization` and `sonar.projectKey` in this file. They must be stored as `SONAR_ORGANISATION_KEY` and `SONAR_PROJECT_KEY` GitHub secrets. sonar.host.url=https://sonarcloud.io sonar.qualitygate.wait=true diff --git a/scripts/docker/dgoss.sh b/scripts/docker/dgoss.sh index a9ad997c..e573a48b 100644 --- a/scripts/docker/dgoss.sh +++ b/scripts/docker/dgoss.sh @@ -1,7 +1,7 @@ #!/bin/bash # shellcheck disable=SC2016,SC2154,SC2166 -# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. # SEE: https://github.com/goss-org/goss/blob/master/extras/dgoss/dgoss diff --git a/scripts/docker/docker.lib.sh b/scripts/docker/docker.lib.sh index 193983ee..313a3f89 100644 --- a/scripts/docker/docker.lib.sh +++ b/scripts/docker/docker.lib.sh @@ -1,7 +1,7 @@ #!/bin/bash # shellcheck disable=SC2155 -# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. set -euo pipefail diff --git a/scripts/docker/docker.mk b/scripts/docker/docker.mk index 49fc456b..a31ad9db 100644 --- a/scripts/docker/docker.mk +++ b/scripts/docker/docker.mk @@ -27,7 +27,7 @@ _docker: # Docker command wrapper - mandatory: cmd=[command to execute]; optiona docker-${cmd} # 'dir' is accessible by the function as environment variable # ============================================================================== -# Quality checks - please, DO NOT edit this section! +# Quality checks - please DO NOT edit this section! docker-shellscript-lint: # Lint all Docker module shell scripts @Quality for file in $$(find scripts/docker -type f -name "*.sh"); do @@ -35,7 +35,7 @@ docker-shellscript-lint: # Lint all Docker module shell scripts @Quality done # ============================================================================== -# Module tests and examples - please, DO NOT edit this section! +# Module tests and examples - please DO NOT edit this section! docker-test-suite-run: # Run Docker test suite @ExamplesAndTests scripts/docker/tests/docker.test.sh diff --git a/scripts/docker/dockerfile-linter.sh b/scripts/docker/dockerfile-linter.sh index a81e5daa..094e1726 100755 --- a/scripts/docker/dockerfile-linter.sh +++ b/scripts/docker/dockerfile-linter.sh @@ -1,6 +1,6 @@ #!/bin/bash -# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. set -euo pipefail diff --git a/scripts/docker/tests/docker.test.sh b/scripts/docker/tests/docker.test.sh index 3f544e18..37921bf2 100755 --- a/scripts/docker/tests/docker.test.sh +++ b/scripts/docker/tests/docker.test.sh @@ -1,7 +1,7 @@ #!/bin/bash # shellcheck disable=SC1091,SC2034,SC2317 -# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. set -euo pipefail diff --git a/scripts/githooks/check-file-format.sh b/scripts/githooks/check-file-format.sh index b15d145a..5a2fbaeb 100755 --- a/scripts/githooks/check-file-format.sh +++ b/scripts/githooks/check-file-format.sh @@ -31,7 +31,7 @@ set +e # files that ec would check is output, with no check done. # # Notes: -# Please, make sure to enable EditorConfig linting in your IDE. For the +# Please make sure to enable EditorConfig linting in your IDE. For the # Visual Studio Code editor it is `editorconfig.editorconfig` that is already # specified in the `./.vscode/extensions.json` file. diff --git a/scripts/githooks/check-markdown-format.sh b/scripts/githooks/check-markdown-format.sh index 9fcb8bcc..105775c3 100755 --- a/scripts/githooks/check-markdown-format.sh +++ b/scripts/githooks/check-markdown-format.sh @@ -18,7 +18,7 @@ set -e # 1 - Files are not formatted correctly # # Notes: -# 1) Please, make sure to enable Markdown linting in your IDE. For the Visual +# 1) Please make sure to enable Markdown linting in your IDE. For the Visual # Studio Code editor it is `davidanson.vscode-markdownlint` that is already # specified in the `./.vscode/extensions.json` file. # 2) To see the full list of the rules, please visit diff --git a/scripts/githooks/check-terraform-format.sh b/scripts/githooks/check-terraform-format.sh index b76d4695..cf2f12b9 100755 --- a/scripts/githooks/check-terraform-format.sh +++ b/scripts/githooks/check-terraform-format.sh @@ -1,6 +1,6 @@ #!/bin/bash -# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. set -euo pipefail diff --git a/scripts/init.mk b/scripts/init.mk index 5b61250f..5cb2bdf2 100644 --- a/scripts/init.mk +++ b/scripts/init.mk @@ -1,4 +1,4 @@ -# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. include scripts/docker/docker.mk include scripts/tests/test.mk @@ -79,7 +79,7 @@ list-variables: # List all the variables available to make @Others .EXPORT_ALL_VARIABLES: .NOTPARALLEL: .ONESHELL: -.PHONY: * # Please, do not change this line! The alternative usage of it introduces unnecessary complexity and is considered an anti-pattern. +.PHONY: * # Please do not change this line! The alternative usage of it introduces unnecessary complexity and is considered an anti-pattern. MAKEFLAGS := --no-print-director SHELL := /bin/bash ifeq (true, $(shell [[ "${VERBOSE}" =~ ^(true|yes|y|on|1|TRUE|YES|Y|ON)$$ ]] && echo true)) diff --git a/scripts/shellscript-linter.sh b/scripts/shellscript-linter.sh index d97b7c96..18400b5a 100755 --- a/scripts/shellscript-linter.sh +++ b/scripts/shellscript-linter.sh @@ -1,6 +1,6 @@ #!/bin/bash -# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. set -euo pipefail diff --git a/scripts/terraform/terraform.lib.sh b/scripts/terraform/terraform.lib.sh index 2206ce79..b19aa28a 100644 --- a/scripts/terraform/terraform.lib.sh +++ b/scripts/terraform/terraform.lib.sh @@ -1,6 +1,6 @@ #!/bin/bash -# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. set -euo pipefail diff --git a/scripts/terraform/terraform.mk b/scripts/terraform/terraform.mk index f62a02fa..2042e7c0 100644 --- a/scripts/terraform/terraform.mk +++ b/scripts/terraform/terraform.mk @@ -48,7 +48,7 @@ _terraform: # Terraform command wrapper - mandatory: cmd=[command to execute]; terraform-${cmd} # 'dir' and 'opts' are accessible by the function as environment variables, if set # ============================================================================== -# Quality checks - please, DO NOT edit this section! +# Quality checks - please DO NOT edit this section! terraform-shellscript-lint: # Lint all Terraform module shell scripts @Quality for file in $$(find scripts/terraform -type f -name "*.sh"); do @@ -56,7 +56,7 @@ terraform-shellscript-lint: # Lint all Terraform module shell scripts @Quality done # ============================================================================== -# Module tests and examples - please, DO NOT edit this section! +# Module tests and examples - please DO NOT edit this section! terraform-example-provision-aws-infrastructure: # Provision example of AWS infrastructure @ExamplesAndTests make terraform-init @@ -73,7 +73,7 @@ terraform-example-clean: # Remove Terraform example files @ExamplesAndTests rm -f ${TERRAFORM_STACK}/.terraform.lock.hcl # ============================================================================== -# Configuration - please, DO NOT edit this section! +# Configuration - please DO NOT edit this section! terraform-install: # Install Terraform @Installation make _install-dependency name="terraform" diff --git a/scripts/terraform/terraform.sh b/scripts/terraform/terraform.sh index fc935307..b24ad5cf 100755 --- a/scripts/terraform/terraform.sh +++ b/scripts/terraform/terraform.sh @@ -1,6 +1,6 @@ #!/bin/bash -# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. set -euo pipefail diff --git a/scripts/tests/test.mk b/scripts/tests/test.mk index 7a254b68..aab47c62 100644 --- a/scripts/tests/test.mk +++ b/scripts/tests/test.mk @@ -1,4 +1,4 @@ -# WARNING: Please, DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. # The test types listed here are both those which might run both locally and in CI, or # in one but not the other. All of the test types listed at