alphagov / govuk-infrastructure

GOV.UK Infrastructure What's in this repo The govuk-infrastructure repo contains: • : Terraform modules for turning up an Kubernetes cluster on EKS for GOV.UK. • : Container image definitions for utilities. • : GitHub Actions and workflows used by other GOV.UK repos, for example release automation, test runners and security analysis tools. What's not in this repo Helm charts for GOV.UK applications are in alphagov/govuk-helm-charts. Base image definitions for GOV.UK Ruby apps are in alphagov/govuk-ruby-images. Configuration of CDN services is stored in alphagov/govuk-fastly and alphagov/govuk-fastly-secrets (private) repos. Toolbox utility is stored in alphagov/govuk-toolbox-image Usage To install the compatible version of Terraform: We set the constraints with minor version precision. However when using this Terraform version manager, you need to specify the patch version, e.g. . Pre-commit hooks We have some recommended pre-commit hooks. You need to install for these to run. Documentation See the directory. There are also docs in the directory and inline in READMEs in some directories. Documentation linting This repository uses Vale to lint our written English prose. Vale applies a variety of rules and heuristics, such as avoiding overly long sentences and not using the passive voice, as well as doing spelling and grammar checks. To run the documentation linting locally, run Installing Vale If you are using a Mac, you can install Vale with Brew: If you are using Linux or Windows, refer to Vale's own guide. Resolving common issues with Vale When using Vale, you will come across a number of common issues and scenarios. Documented here are the scenarios and how to handle them Vale says a product name or a plural acronym is an incorrect spelling Vale uses an open source dictionary to spell check our work. It does not know about proper nouns, and will frequently ask if you meant to spell it that way. If you are confident that you are right, there are two steps to take • Add the word to the vocabulary file in alphabetical order . You can use limited regular expressions such as to match both and in a single entry. • If the word is the name of a product, add it the rule in . This Vale rule enforces us using the correct spelling of a product name by matching common or potential misspellings using regular expressions, and suggesting the correct spelling. Using the AWS service CloudWatch as an example, common misspellings include , , and . To match all of these and suggest the correct spelling, add an entry such as this: Vale says a common acronym should be defined We have a Vale rule that requires acronyms to be defined the first time it's used in a document. For example, instead of we should write the first time, then just later. However, there are exceptions to that rule in two places: • The rule's definition in . This list contains acronyms we think would be well known to the general public, such as BBC or CCTV. The list is drawn from the official GOV.UK writing style guide. • The vocabulary file in . This list contains acronyms that we think would be well known to somebody reading our documentation, such as HTTPS or CLI. If you think the acronym would be well known to either of these groups, add it to the correct list. Vale is reporting an error that is wrong in context Vale can sometimes be wrong about our writing. It is imperfect. For example, it will report not using sentence casing in a title as an error when the title contains proper nouns. You can turn off a rule for a paragraph the offending line or paragraph with a comment containing the rule name: Comments with the vale directive must have nothing else in the same comment. The comment before the rule is turned back on, which explains why the rule is not necessary, is not required. However, it is a good convention for you to follow. Add a new linting rule You can create a new linting rule by adding a YAML file in one of two places: and . The former contains rules that match the rules of the official GOV.UK writing style guide, and the latter contains additional rules for our own writing. You should refer to the checks section of the official Vale documentation for the structure and format of rules files. Team GOV.UK Platform Engineering team looks after this repo. If you're inside GDS, you can find us in #govuk-ask-platform-engineering or view our kanban board. Licence MIT License