Update README and CONTRIBUTING guidelines

.circleci/config.yml

@@ -9,7 +9,7 @@ jobs:
       - checkout
       - run:
           name: Install pytest
-          command: pip install pytest
+          command: make install
       - run:
           name: Test git commits
           command: make test
@@ -36,12 +36,13 @@ jobs:
 
   prettier:
     docker:
-      - image: tmknom/prettier:3.0.0
+      # See https://hub.docker.com/r/tmknom/prettier/tags for available tags.
+      - image: tmknom/prettier:3.2.5
     steps:
       - checkout
       - run:
           name: Check Prettier
-          command: prettier --check .
+          command: prettier --check --parser=markdown .
 
 workflows:
   static-analysis:

.gitignore

@@ -0,0 +1 @@
+.python-version

.prettierignore

@@ -1,3 +1,8 @@
 *.yml
 *.yaml
 *.json
+.pytest_cache/
+.circleci/
+.prettierignore
+.spelling
+makefile

.spelling

@@ -17,6 +17,8 @@ sendgrid
 stylelint
 vscode
 webtest
+homebrew
+markdownlint
 
 # Terminology
 ORM-constructs

CONTRIBUTING.md

@@ -1,90 +1,106 @@
 # Contributing
 
-Markdown code in this repo must pass several static analysis tests, which are
-detailed below. Note that you can run:
+You're welcome to suggest changes if you spot a broken link or typo. Clone the
+repo or use the GitHub UI to make a pull request.
 
-```sh
-make ci
-```
+## Installation
 
-to run these checks before pushing to Github.
+Several tests are run on changes in CI. To replicate these tests locally, you'll
+need to install some tools. None are essential but they will detect possible
+problems before CI does.
 
-## Git commit subjects
-
-Git commit subjects must:
-
-- Be no longer than 70 characters;
-- Start with a capital letter;
-- Not end with a full stop;
-
-Further, pull request branches should rebase off `main` to incorporate upstream
-changes; don't merge `main` into your branch.
+### Prettier
 
-These rules are checked using Pytest in CI.
+Ensure [Prettier](https://prettier.io/) version 3.2.5 is installed. It can be installed with:
 
-## Formatting
+    npm install -g [email protected]
 
-All markdown should be formatted with [Prettier](https://prettier.io/) version 3.0.0
-This can be installed on your host OS with:
+Verify the installed version is correct with:
 
-    npm install -g [email protected]
+    prettier --version
 
 Once installed, ensure your editor runs Prettier on a pre-save hook:
 
 - [PyCharm instructions](https://www.jetbrains.com/help/pycharm/prettier.html)
 - [VSCode instructions](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
 - [Vim instructions](https://prettier.io/docs/en/vim.html)
 
-Prettier conformance is checked in CI and configured via `.prettierrc.yaml` and
-`.prettierignore`.
+### Docker
 
-## Spelling
+Ensure you have Docker installed and [you have an account](https://www.docker.com/get-started/).
+Mac users can [install from Homebrew](https://formulae.brew.sh/formula/docker).
 
-Pull requests must pass a spell-check before merge. This is done using the
-[`tmaier/markdown-spellcheck`](https://hub.docker.com/r/tmaier/markdown-spellcheck)
-Docker image.
+### Python tooling
 
-To run the spell-test locally run:
+Ensure you have a Python 3.11 virtual environment created for this project and
+Python packages have been installed with `make install`.
 
-    make spell_check
+There are various ways of doing this - here is one that uses `pyenv` and `pyenv-virtualenvwrapper`:
 
-or:
+```sh
+pyenv local 3.11.4  # Match the version in `.circleci/config.yml`
+mkvirtualenv conventions
+make install
+```
 
-    docker run --rm -ti -v $(pwd):/workdir tmaier/markdown-spellcheck:latest \
-        --report --ignore-numbers --ignore-acronyms "**/*.md"
+## Development
 
-Add exceptions to the custom dictionary in `.spelling`.
+### Formatting
 
-## Linting
+Markdown should be formatted with Prettier using the configuration in
+`.prettierrc.yaml`. Verify this with:
 
-Markdown files are linted by
-[`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli).
+```sh
+make prettier_check
+```
 
-To run the linting locally run:
+### Linting
 
-    docker run -i --rm -v `pwd`:/work tmknom/markdownlint:0.33.0
+Markdown should conform to the Markdownlint rules declared in
+`.markdownlint.yaml`. Verify this with:
 
-or, if installed on your host OS, run:
+```sh
+make markdownlint
+```
 
-    markdownlint .
+### Spelling
 
-or:
+Markdown must pass a spell-check. Verify this with:
 
-    make markdownlint
+```sh
+make spell_check
+```
+
+Spelling exceptions are held in `.spelling`.
 
-Configuration for the enforced rules is in `.markdownlint.yaml`.
+### Commit messages
 
-Many linting issues can be fixed by running:
+Git commit subjects must:
 
-    markdownlint --fix .
+- Be no longer than 70 characters.
+- Start with a capital letter.
+- Not end with a full stop.
 
-## Preview rendered pages
+Further, PR branches should rebase off `main` to incorporate upstream
+changes; don't merge `main` into your branch.
+
+These rules are checked using Pytest in CI. Verify conformance with:
+
+```sh
+make test
+```
+
+### Preview rendered pages
 
 You can use [`grip`](https://github.com/joeyespo/grip) to render Github-flavour
 markdown files. Install with:
 
-    brew install grip
+```sh
+brew install grip
+```
 
 While working on docs, run a local, auto-reloading server with:
 
-    make server
+```sh
+make server
+```

README.md

@@ -11,7 +11,7 @@ the complete set of Kraken Tech coding conventions, you'll need to [apply for a
 here][jobs] 😜.
 
 [group]: https://octopusenergy.group/
-[jobs]: https://jobs.lever.co/octoenergy?department=Kraken%20Technologies%20%F0%9F%93%88
+[jobs]: https://kraken.tech/jobs
 
 Contents:
 

makefile

@@ -1,13 +1,20 @@
+# Run all checks run in CI.
 ci: test markdownlint spell_check prettier_check
 
 test:
 	pytest -v .circleci/
 
 markdownlint:
-	markdownlint .
+	docker run --rm -v $$(pwd):/work tmknom/markdownlint:0.33.0 -- .
 
 spell_check:
 	docker run --rm -ti -v $$(pwd):/workdir tmaier/markdown-spellcheck:latest --report --ignore-numbers --ignore-acronyms  "**/*.md"
 
 prettier_check:
 	prettier --check --parser=markdown .
+
+install:
+	pip install pytest==8.3.4
+
+server:
+	grip