Check markdown format (#267)

* Add GitHub workflow action step to check markdown

* Do not check markdown if no file is changed

* Compare against the origin branch

* Remove interactive and tty flags

* Debug

* Ignore list with just spaces

* Debug

* Debug

* Remove debug code

* An attempt to fail the action by touching a markdown file

* Fix formatting issues except CONTRIBUTING.md file

* Show files

* Check moved and renamed files

* All issues fixed for the changed markdown files

* Allow MD033 inline HTML

Author: stefaniuk

.github/workflows/action.yml

@@ -0,0 +1,29 @@
+name: Check Markdown
+on:
+  push:
+    branches: ['**']
+  pull_request:
+    types: [opened, synchronize, reopened]
+jobs:
+  markdown-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Check links
+        uses: gaurav-nelson/[email protected]
+        with:
+          use-quiet-mode: 'yes'
+      - name: Check format
+        # 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.
+        run: |
+          files=$(git diff --diff-filter=ACMRT --name-only origin/${{ github.event.repository.default_branch }}.. "*.md")
+          if [ -n "$files" ]; then
+            docker run --rm \
+              -v $PWD:/workdir \
+              ghcr.io/igorshubovych/markdownlint-cli:latest \
+                $files \
+                --disable MD013 MD033
+          fi

.github/workflows/check-markdown.yml

@@ -1,4 +1,5 @@
 # Welcome to the Engineering Framework contributors guide
+
 Thank you for your interest in improving the framework.
 
 In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.
@@ -8,17 +9,20 @@ The framework is concerned with engineering best practice at NHSD, however, oper
 If you're new to Github and/or Markdown, Github's own [contributor's guide](https://github.com/github/docs/blob/main/CONTRIBUTING.md) provides good signposting on these topics.
 
 ## Using issues
+
 If you have a change (or a new page) to raise, please create an [issue](https://github.com/NHSDigital/software-engineering-quality-framework/issues) first, and reference it in your commits. Before raising a new issue, have a look through the existing ones in case it's already been raised (Framework owners will strive to keep the list small enough).
 
 ## Pull requests and merging
+
 You can't push to the main branch. Therefore, for all changes you will need to create a new branch, and then a pull request to merge said branch into main. The framework owners will be nominated as reviewers of your PR by default, but feel free to add other people as well if you think they will have valuable input.
 
 When committing your changes, please reference the issue they're resolving, so it will be closed automatically (e.g. `Closes #123`).
 
 ## Contributing guidelines and etiquette
+
 * Preview your Markdown code to make sure the format is not broken.
 * Check grammar, spelling and punctuation, no one wants to look pedantic by requesting changes due to typos or inconsistent grammar/syntax, but it's only fair to keep this tidy.
 * The framework is open to the world. This has a few implications:
   * Nothing in it should be confidential, private to NHSD or include any personal data.
   * All links in framework pages should be public.
-* Use [inclusive language](../inclusive-language.md): avoid terms which cause hurt and offence, including if they have historically been considered industry-standard terms.
+* Use [inclusive language](inclusive-language.md): avoid terms which cause hurt and offence, including if they have historically been considered industry-standard terms.

.github/CONTRIBUTING.md renamed to CONTRIBUTING.md

@@ -9,14 +9,17 @@ See the [Quick Start Guide](quickstart.md)
 This framework is concerned with using "good" software engineering to support rapid and safe delivery of high-quality software, at scale
 
 It aims to:
+
 1. Describe a shared (across multiple teams) definition of "good" engineering
 2. Provide tools for teams to gain insight into their current engineering maturity levels and their level of [technical debt](tech-debt.md)
 3. Provide resources to support teams to increase their engineering maturity levels and manage their [technical debt](tech-debt.md)
 
 ![Ecosystem](images/engineering-ecosystem.png)
+
 ## Philosophy
 
 The philosophy underpinning this framework advocates:
+
 * Engineering led by user needs and service outcomes
 * Empowered delivery teams which are accountable for their products
 * Products must be actively maintained for their entire lifecycle
@@ -29,6 +32,7 @@ The philosophy underpinning this framework advocates:
 ## Context
 
 The framework is a companion to:
+
 * The [NHS service standard](https://service-manual.nhs.uk/service-standard), with cross-references in this format: [SERVICE-RELIABILITY](https://service-manual.nhs.uk/service-standard/14-operate-a-reliable-service)
 * The [NHS Digital architectural principles](https://digital.nhs.uk/about-nhs-digital/our-work/nhs-digital-architecture/principles), with cross-references in this format: [ARCHITECTURE-SECURITY](https://digital.nhs.uk/about-nhs-digital/our-work/nhs-digital-architecture/principles/adopt-appropriate-cyber-security-standards)
 
@@ -46,4 +50,5 @@ The framework consists of:
 * Guidance on how to practice [continuous improvement](continuous-improvement.md)
 
 ## Contributing
-See our [contributor's guide](./.github/CONTRIBUTING.md)
+
+See our [contributor's guide](CONTRIBUTING.md)

README.md

@@ -7,39 +7,39 @@
 
 ## Background
 
-The language and terminology we use is important, and there are certain industry-standard terms which cause hurt and offence. Furthermore, the 'old' standard terms use arbitrary language, for example replacing White / Black with terms such as Allow / Deny or Permit / Block removes ambiguity and delivers a better experience for all users. 
+The language and terminology we use is important, and there are certain industry-standard terms which cause hurt and offence. Furthermore, the 'old' standard terms use arbitrary language, for example replacing White / Black with terms such as Allow / Deny or Permit / Block removes ambiguity and delivers a better experience for all users.
 
 In line with organisations such as the [Home Office](https://hodigital.blog.gov.uk/2020/07/23/not-a-black-and-white-issue-using-racially-neutral-terms-in-technology/) and the [National Cyber Security Centre](https://www.ncsc.gov.uk/blog-post/terminology-its-not-black-and-white), we recognise that historically we have used these terms, and we will strive to avoid using these terms in the future.
 
 ## Details
 
-| Context                         | Term we will avoid    | Terms we will use instead (suggested) | 
-| :------------------------------ | :-------------------- | :------------------------------------ |
-| Infrastructure (e.g. databases) | Master                | Primary                               | 
-| Infrastructure (e.g. databases) | Slave                 | Replica / Secondary / Worker / Agent  | 
-| Source control                  | Master                | Main (see [below](#renaming-the-master-branch-in-github) for GitHub notes) |
-| Security / permissions          | Whitelist             | Allowlist / Permitlist                |
-| Security / permissions          | Blacklist             | Denylist / Blocklist                  |
+| Context                         | Term we will avoid | Terms we will use instead (suggested)                                      |
+| :------------------------------ | :----------------- | :------------------------------------------------------------------------- |
+| Infrastructure (e.g. databases) | Master             | Primary                                                                    |
+| Infrastructure (e.g. databases) | Slave              | Replica / Secondary / Worker / Agent                                       |
+| Source control                  | Master             | Main (see [below](#renaming-the-master-branch-in-github) for GitHub notes) |
+| Security / permissions          | Whitelist          | Allowlist / Permitlist                                                     |
+| Security / permissions          | Blacklist          | Denylist / Blocklist                                                       |
 
-Note: this is not intended to be an exhaustive list, and further suggestions are [very welcome](.github/CONTRIBUTING.md).
+Note: this is not intended to be an exhaustive list, and further suggestions are [very welcome](CONTRIBUTING.md).
 
 ## Renaming the master branch in GitHub
 
 GitHub have published [guidance](https://github.com/github/renaming) around renaming the master branch. It is worth noting that GitHub retains a history of the names of the parent branch so that existing links to your repository aren't broken - for example the parent branch in this repository has been renamed from master to main, but old links to the master address still work ([https://github.com/NHSDigital/software-engineering-quality-framework/blob/master/README.md](https://github.com/NHSDigital/software-engineering-quality-framework/blob/master/README.md)) and are automatically redirected to the main branch.
 
 In addition to the guidance from GitHub, developers will need to update local copies of a repository if the "master" branch is renamed - this example is for a renaming from master to main:
 
-```
+```bash
 git branch -m master main
 git fetch origin
 git branch -u origin/main main
 git remote set-head origin -a
 ```
+
 ## Further reading
 
 * [inclusivenaming.org](https://inclusivenaming.org/word-lists/overview/)
 * [Internet Engineering Task Force](https://datatracker.ietf.org/doc/draft-knodel-terminology/)
 * [Python](https://bugs.python.org/issue34605)
 * [GitHub](https://github.com/github/renaming)
 * [NCSC](https://www.ncsc.gov.uk/blog-post/terminology-its-not-black-and-white)
-

inclusive-language.md

@@ -66,8 +66,6 @@
       "**/target": true,
       "**/tmp": true
     },
-    "telemetry.enableCrashReporter": false,
-    "telemetry.enableTelemetry": false,
     "terminal.integrated.fontFamily": "Hack Nerd Font",
     "window.title": "${activeEditorMedium}${separator}${rootName}${separator}${rootPath}",
     "window.zoomLevel": 0,
@@ -131,35 +129,9 @@
       "editor.insertSpaces": true,
       "editor.tabSize": 2
     },
-    "yaml.customTags": [
-      "!And",
-      "!And sequence",
-      "!If",
-      "!If sequence",
-      "!Not",
-      "!Not sequence",
-      "!Equals",
-      "!Equals sequence",
-      "!Or",
-      "!Or sequence",
-      "!FindInMap",
-      "!FindInMap sequence",
-      "!Base64",
-      "!Join",
-      "!Join sequence",
-      "!Cidr",
-      "!Ref",
-      "!Sub",
-      "!Sub sequence",
-      "!GetAtt",
-      "!GetAZs",
-      "!ImportValue",
-      "!ImportValue sequence",
-      "!Select",
-      "!Select sequence",
-      "!Split",
-      "!Split sequence"
-    ],
+    "yaml.schemas": {
+      "https://json.schemastore.org/github-workflow.json": "file://./.github/workflows/check-markdown.yml"
+    },
     "workbench.colorCustomizations": {
       "activityBar.activeBackground": "#1accff",
       "activityBar.activeBorder": "#df00ad",
@@ -168,10 +140,7 @@
       "activityBar.inactiveForeground": "#15202b99",
       "activityBarBadge.background": "#df00ad",
       "activityBarBadge.foreground": "#e7e7e7",
-      "editorGroup.border": "#1accff",
-      "panel.border": "#1accff",
       "sash.hoverBorder": "#1accff",
-      "sideBar.border": "#1accff",
       "statusBar.background": "#00b3e6",
       "statusBar.foreground": "#15202b",
       "statusBarItem.hoverBackground": "#008bb3",
@@ -182,6 +151,6 @@
       "titleBar.inactiveBackground": "#00b3e699",
       "titleBar.inactiveForeground": "#15202b99"
     },
-    "peacock.color": "#00b3e6"
+    "peacock.color": "#00b3e6",
   }
 }