Initial commit

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+[{Dockerfile,Dockerfile.}*]
+indent_size = 4
+
+[*{.mk,Makefile}]
+indent_style = tab

.github/workflows/check-file-format.yaml

@@ -0,0 +1,14 @@
+name: Check File Format
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+jobs:
+  check-file-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: ./scripts/githooks/editorconfig-pre-commit.sh

LICENCE.md

@@ -0,0 +1,21 @@
+# MIT Licence
+
+Copyright (c) 2023 Crown Copyright NHS England.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,5 @@
+config: githooks-install
+
+githooks-install:
+	echo "./scripts/githooks/pre-commit" > .git/hooks/pre-commit
+	chmod +x .git/hooks/pre-commit

README.md

@@ -0,0 +1,70 @@
+# Repository Template
+
+Start with an overview or a brief description of what the project is about and what it does.
+
+There is an expectation that each file of this repository template is concise and self-documented.
+
+## Table of Contents
+
+- [Repository Template](#repository-template)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+    - [Prerequisites](#prerequisites)
+  - [Usage](#usage)
+  - [Architecture](#architecture)
+    - [Diagrams](#diagrams)
+    - [Configuration](#configuration)
+  - [Contributing](#contributing)
+  - [Contacts](#contacts)
+  - [Licence](#licence)
+
+## Installation
+
+By including preferably a one-liner or if necessary a set of clear CLI instructions we improve user experience. This should be a frictionless installation process that works on various operating systems (macOS, Linux, Windows WSL) and handles all the dependencies.
+
+```shell
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/org/repo/branch/install.sh)"
+```
+
+### Prerequisites
+
+The following software packages or their equivalents are expected to be installed
+
+- [GNU make](https://www.gnu.org/software/make/)
+- [Docker](https://www.docker.com/)
+
+## Usage
+
+After a successful installation, provide an informative example of how this project can be used. Additional code snippets, screenshots and demos work well in this space. You may also link to the other documentation resources, e.g. the [User Guide](./docs/user-guide.md) to demonstrate more use cases and to show more features.
+
+## Architecture
+
+### Diagrams
+
+The [C4 model](https://c4model.com/) is a simple and intuitive way to create software architecture diagrams that are clear, consistent, scalable and most importantly collaborative. This should result in documenting all the system interfaces, external dependencies and integration points.
+
+### Configuration
+
+Most of the projects are built with customisability and extendability in mind. At a minimum, this can be achieved by implementing service level configuration options and settings. The intention of this section is to show how this can be used. If the system processes data, you could mention here for example how the input is prepared for testing - anonymised, synthetic or live data.
+
+## Contributing
+
+Describe or link templates on how to raise an issue, feature request or make a contribution to the codebase. Reference the other documentation files, like
+
+- Environment setup for contribution, i.e. `CONTRIBUTING.md`
+- Coding standards, branching, linting, practices for development and testing
+- Release process, versioning, changelog
+- Backlog, board, roadmap, ways of working
+- High-level requirements, guiding principles, decision records, etc.
+
+## Contacts
+
+Provide a way to contact the owners of this project. It can be a team, an individual or information on the means of getting in touch via active communication channels, e.g. opening a GitHub discussion, raising an issue, etc.
+
+## Licence
+
+> The [LICENCE.md](./LICENCE.md) file will need to be updated with the correct year and owner
+
+Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.
+
+Any HTML or Markdown documentation is [© Crown Copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) and available under the terms of the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

docs/ADR-001: Use git hook and GitHub action to check the .editorconfig compliance.md

@@ -0,0 +1,129 @@
+# ADR-001: Use git hook and GitHub Action to check the `.editorconfig` compliance
+
+>|              | |
+>| ------------ | --- |
+>| Date         | `26/04/2023` |
+>| Status       | `RFC` |
+>| Deciders     | `Engineering` |
+>| Significance | `Construction techniques` |
+>| Owners       | `Dan Stefaniuk, Amaan Ibn-Nasar` |
+
+---
+
+- [ADR-001: Use git hook and GitHub Action to check the `.editorconfig` compliance](#adr-001-use-git-hook-and-github-action-to-check-the-editorconfig-compliance)
+  - [Context](#context)
+  - [Decision](#decision)
+    - [Assumptions](#assumptions)
+    - [Drivers](#drivers)
+    - [Options](#options)
+      - [Options 1: The pre-commit project](#options-1-the-pre-commit-project)
+      - [Options 2a: Custom shell script](#options-2a-custom-shell-script)
+      - [Options 2b: Docker-based custom shell script](#options-2b-docker-based-custom-shell-script)
+      - [Option 3: A GitHub Action from the Marketplace](#option-3-a-github-action-from-the-marketplace)
+    - [Outcome](#outcome)
+    - [Rationale](#rationale)
+  - [Consequences](#consequences)
+  - [Compliance](#compliance)
+  - [Notes](#notes)
+  - [Tags](#tags)
+
+## Context
+
+As part of the Repository Template project a need for a simple text formatting feature using the [EditorConfig](https://editorconfig.org/) rules was identified that is accessible and consistent for all contributors. To ensure that formatting rules are applied, a compliance check has to be implemented on a developer workstation and as a part of the CI/CD pipeline. This will establish a fast feedback loop and a fallback option, if the former has not worked.
+
+## Decision
+
+### Assumptions
+
+This decision is based on the following assumptions that are used to form a set of generic requirements for the implementation as a guide. A solution should be
+
+- Cross-platform and portable, supporting systems like
+  - macOS
+  - Windows WSL (Ubuntu)
+  - Ubuntu and potentially other Linux distributions like Alpine
+- Configurable
+  - can run on a file or a directory
+  - can be turned on/off entirely
+- Run locally (aka developer workstation) and remotely (aka CI/CD pipeline)
+- Reusable and avoid code duplication
+
+### Drivers
+
+Implementation of this compliance check will help with any potential debate or discussion, removing personal preferences and opinions, enabling teams to focus on delivering value to the product they work on.
+
+### Options
+
+#### Options 1: The [pre-commit](https://pre-commit.com/) project
+
+- Pros
+  - Python is installed on most if not all platforms
+  - A pythonist friendly tool
+  - Well-documented
+- Cons
+  - Dependency on Python even for a non-Python project
+  - Potential versioning issues with Python runtime and dependencies compatibility
+  - Lack of process isolation, access to resources with user-level privileges
+  - Dependency on multiple parties and plugins
+
+#### Options 2a: Custom shell script
+
+- Pros
+  - Execution environment is installed everywhere, no setup required
+  - Ease of maintainability and testability
+  - It is a simple solution
+- Cons
+  - May potentially require more coding in Bash
+  - Requires shell scripting skills
+
+#### Options 2b: Docker-based custom shell script
+
+This option is an extension built upon option 2a.
+
+- Pros
+  - Cross-platform compatibility
+  - Isolation of the process dependencies and runtime
+  - Docker is an expected dependency for most/all projects
+- Cons
+  - Requires Docker as a preinstalled dependency
+  - Requires basic Docker skills
+
+#### Option 3: A GitHub Action from the Marketplace
+
+- Pros
+  - Usage of a GitHub native functionality
+- Cons
+  - 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
+
+The decision is to implement Option 2b.
+
+### Rationale
+
+A choice of shell scripting along with Docker offers a good support for simplicity, process isolation, portability across the operating systems and reuse of the same code and its configuration. This approach makes it consistent for a local environment and the CI/CD pipeline, where the process can be gated and compliance enforced.
+
+## Consequences
+
+As a result of the above decision
+
+- a single Bash script will be implemented
+- it will be placed in the `scripts/githooks` directory
+- the name of the file will be `editorconfig-pre-commit.sh`
+- there will be a `pre-commit` runner included
+- the GitHub Action will call the git hook `editorconfig-pre-commit.sh` script directly
+- and a couple of `Makefile` targets like `config`, `githooks-install` will be implemented to bootstrap the project
+
+The intention of this decision is to guide any other git hook and GitHub Action implementations.
+
+## Compliance
+
+Both, the git hook and the GitHub Action should be executed automatically as part of the developer workflow.
+
+## 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.
+
+## Tags
+
+`#maintainability, #testability, #simplicity, #security`

scripts/githooks/editorconfig-pre-commit.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# Pre-commit git hook to check the EditorConfig rules complience over changed files
+#
+# Usage:
+#   $ ./editorconfig-pre-commit.sh
+#
+# Exit codes:
+#   0 - all files are formatted correctly
+#   1 - files are not formatted correctly
+#
+# Notes:
+#   Due to the file name escaping issue files are checked one by one.
+
+# ==============================================================================
+
+exit_code=0
+image_digest=0f8f8dd4f393d29755bef2aef4391d37c34e358d676e9d66ce195359a9c72ef3 # 2.7.0
+changed_files=$(git diff --name-only --diff-filter=ACMRT)
+
+while read file; do
+    docker run --rm --platform linux/amd64 \
+        --volume=$PWD:/check \
+        mstruebing/editorconfig-checker@sha256:$image_digest \
+            ec \
+                --exclude '.git/' \
+                "$file"
+    [ $? != 0 ] && exit_code=1 ||:
+done < <(echo "$changed_files")
+[ $? != 0 ] && exit_code=1 ||:
+
+exit $exit_code

scripts/githooks/pre-commit

@@ -0,0 +1,15 @@
+#!/bin/bash -e
+
+# Pre-commit git hook runner
+
+# ==============================================================================
+
+project_dir=$(git rev-parse --show-toplevel)
+cd $project_dir
+
+pre_commit_scripts=$(ls -1 $project_dir/scripts/githooks/*-pre-commit.sh 2> /dev/null)
+for script in $pre_commit_scripts; do
+  printf "Running githook: $(echo $script | sed "s;$project_dir/;;g")\n"
+  $script "$@"
+done
+printf "Successfully run all githooks\n"