From 4cc6060c3282cfdafa83171ea2e0741268b6a1d9 Mon Sep 17 00:00:00 2001 From: Thomas Judd-Cooper Date: Fri, 14 Jul 2023 23:10:59 +0100 Subject: [PATCH] Remove un-used ADRs --- ...n to check the .editorconfig compliance.md | 142 ------------------ ...- Scan repository for hardcoded secrets.md | 98 ------------ 2 files changed, 240 deletions(-) delete mode 100644 docs/adr/ADR-001 - Use git hook and GitHub action to check the .editorconfig compliance.md delete mode 100644 docs/adr/ADR-002 - Scan repository for hardcoded secrets.md 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 deleted file mode 100644 index a84bc71..0000000 --- a/docs/adr/ADR-001 - Use git hook and GitHub action to check the .editorconfig compliance.md +++ /dev/null @@ -1,142 +0,0 @@ -# ADR-001: Use git hook and GitHub Action to check the `.editorconfig` compliance - ->| | | ->| ------------ | --- | ->| Date | `15/05/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 (like text encoding, line endings, tabs vs. spaces etc.) 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. - -Other linting tools like for example [Prettier](https://prettier.io/) and [ESLint](https://eslint.org/) are not considered here as they are code formatting tools dedicated to specific technologies and languages. The main drivers for this decision are the style consistency across all files in the codebase and to eliminate any disruptive changes introduced based on preferences. EditorConfig rules are recognised and supported by most if not all major editors and IDEs. - -Here is the recommended ruleset: - -```console -charset = utf-8 -end_of_line = lf -indent_size = 2 -indent_style = space -insert_final_newline = true -trim_trailing_whitespace = true -``` - -### 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` diff --git a/docs/adr/ADR-002 - Scan repository for hardcoded secrets.md b/docs/adr/ADR-002 - Scan repository for hardcoded secrets.md deleted file mode 100644 index dded6ee..0000000 --- a/docs/adr/ADR-002 - Scan repository for hardcoded secrets.md +++ /dev/null @@ -1,98 +0,0 @@ -# ADR-002: Scan repository for hardcoded secrets - ->| | | ->| ------------ | --- | ->| Date | `31/05/2023` | ->| Status | `RFC` | ->| Deciders | `Engineering` | ->| Significance | `Construction techniques` | ->| Owners | `Dan Stefaniuk, Jon Pearce, Tamara Goldschmidt, Tim Rickwood` | - ---- - -- [ADR-002: Scan repository for hardcoded secrets](#adr-002-scan-repository-for-hardcoded-secrets) - - [Context](#context) - - [Decision](#decision) - - [Assumptions](#assumptions) - - [Drivers](#drivers) - - [Options](#options) - - [Outcome](#outcome) - - [Rationale](#rationale) - - [Consequences](#consequences) - - [Compliance](#compliance) - - [Notes](#notes) - - [Actions](#actions) - - [Tags](#tags) - -## Context - -- Review git-secrets decision - - To compare - - tools - - 1. https://github.com/awslabs/git-secrets - - 2. https://github.com/trufflesecurity/trufflehog - - 3. https://github.com/gitleaks/gitleaks - - repo metadata - - contributions (data and number) - - stars & forks - - language - - licence - - features - - scan whole history - - scan single commit - - predefined set of rules - - patterns: custom rules - - patterns: exclusions - - entropy detection - - run as a docker image (locally and in CI/CD pipeline) - -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 - -### 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. - -### Drivers - -List the decision drivers that motivate this change or course of action. This may include any identified risks and residual risks after applying the decision. - -### Options - -Consider a comprehensive set of alternative options; provide weighting if applicable. - -### Outcome - -State the decision outcome as a result of taking into account all of the above. Is it a reversible or irreversible decision? - -### Rationale - -Provide a rationale for the decision that is based on weighing the options to ensure that the same questions are not going to be asked again and again unless the decision needs to be superseded. - -For non-trivial decisions a comparison table can be useful for the reviewer. Decision criteria down one side, options across the top. You'll likely find decision criteria come from the Drivers section above. Effort can be an important driving factor. You may have an intuitive feel for this, but reviewers will not. T-shirt sizing the effort for each option may help communicate. - -## Consequences - -Describe the resulting context, after applying the decision. All the identified consequences should be listed here, not just the positive ones. Any decision comes with many implications. For example, it may introduce a need to make other decisions as an effect of cross-cutting concerns; it may impact structural or operational characteristics of the software, and influence non-functional requirements; as a result, some things may become easier or more difficult to do because of this change. What are the trade-offs? - -What are the conditions under which this decision no longer applies or becomes irrelevant? - -## Compliance - -Establish how the success is going to be measured. Once implemented, the effect might lend itself to be measured, therefore if appropriate a set of criteria for success could be established. Compliance checks of the decision can be manual or automated using a fitness function. If it is the latter this section can then specify how that fitness function would be implemented and whether there are any other changes to the codebase needed to measure this decision for compliance. - -## Notes - -Include any links to existing epics, decisions, dependencies, risks, and policies related to this decision record. This section could also include any further links to configuration items within the project or the codebase, signposting to the areas of change. - -It is important that if the decision is sub-optimal or the choice is tactical or misaligned with the strategic directions the risk related to it is identified and clearly articulated. As a result of that, the expectation is that a [Tech Debt](./tech-debt.md) record is going to be created on the backlog. - -## Actions - -- [x] name, date by, action -- [ ] name, date by, action - -## Tags - -`#maintainability, #testability, #simplicity, #security`