From c9139cd4513acad5f239c856a087c6f90333eb11 Mon Sep 17 00:00:00 2001 From: ioreka Date: Mon, 6 Jan 2025 12:33:03 +0000 Subject: [PATCH 1/6] Update jobs link from octo to kraken --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 53981fe..0d38d38 100644 --- a/README.md +++ b/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: From 53e4980f801643597cb8c2b4a1674ad80f02c83a Mon Sep 17 00:00:00 2001 From: ioreka Date: Mon, 6 Jan 2025 13:00:54 +0000 Subject: [PATCH 2/6] First TW pass over the CONTRIB page Splitting into sections and including a clear Installation section --- CONTRIBUTING.md | 98 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 64 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d43811..8e5e8bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,44 +1,59 @@ # 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 PR. + +## Installation + +You'll need a few tools to make and test your changes before pushing them to a PR. + +### Prettier + +All Markdown should be formatted with [Prettier](https://prettier.io/) version 3.1 +Install with: ```sh -make ci +npm install -g prettier@3.1 ``` -to run these checks before pushing to Github. +Once installed, ensure your editor runs Prettier on a pre-save hook: -## Git commit subjects +- [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) -Git commit subjects must: +Prettier conformance is checked in CI and configured via `.prettierrc.yaml` and +`.prettierignore`. -- Be no longer than 70 characters; -- Start with a capital letter; -- Not end with a full stop; +### Docker -Further, pull request branches should rebase off `main` to incorporate upstream -changes; don't merge `main` into your branch. +### Pyenv -These rules are checked using Pytest in CI. +## Development -## Formatting +### Run CI tests locally -All markdown should be formatted with [Prettier](https://prettier.io/) version 3.0.0 -This can be installed on your host OS with: +If your changes include Markdown, be aware that Markdown code in this repo must pass several static analysis tests. Before pushing to GitHub, run - npm install -g prettier@3.0.0 +```sh +make ci +``` -Once installed, ensure your editor runs Prettier on a pre-save hook: +to run these checks. -- [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) +### Git commit subjects -Prettier conformance is checked in CI and configured via `.prettierrc.yaml` and -`.prettierignore`. +Git commit subjects must: + +- Be no longer than 70 characters. +- Start with a capital letter. +- Not end with a full stop. + +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. -## Spelling +### Spelling 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) @@ -46,45 +61,60 @@ Docker image. To run the spell-test locally run: - make spell_check +```sh +make spell_check +``` or: - - docker run --rm -ti -v $(pwd):/workdir tmaier/markdown-spellcheck:latest \ - --report --ignore-numbers --ignore-acronyms "**/*.md" +```sh +docker run --rm -ti -v $(pwd):/workdir tmaier/markdown-spellcheck:latest \ + --report --ignore-numbers --ignore-acronyms "**/*.md" +``` Add exceptions to the custom dictionary in `.spelling`. -## Linting +### Linting Markdown files are linted by [`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli). To run the linting locally run: - docker run -i --rm -v `pwd`:/work tmknom/markdownlint:0.33.0 +```sh +docker run -i --rm -v `pwd`:/work tmknom/markdownlint:0.33.0 +``` or, if installed on your host OS, run: - markdownlint . +```sh +markdownlint . +``` or: - make markdownlint +```sh +make markdownlint +``` Configuration for the enforced rules is in `.markdownlint.yaml`. Many linting issues can be fixed by running: - markdownlint --fix . +```sh +markdownlint --fix . +``` ## 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 +``` From 8c48af5f6adc1fb371acde1702668f044599e8ce Mon Sep 17 00:00:00 2001 From: ioreka Date: Mon, 6 Jan 2025 13:16:56 +0000 Subject: [PATCH 3/6] Fix typo and failing tests --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8e5e8bd..845513d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,9 +24,9 @@ Once installed, ensure your editor runs Prettier on a pre-save hook: Prettier conformance is checked in CI and configured via `.prettierrc.yaml` and `.prettierignore`. -### Docker +### Docker -### Pyenv +### Pytest ## Development From 6dd550cbf2416d0d8c92f623ce12e174c9f31d42 Mon Sep 17 00:00:00 2001 From: ioreka Date: Mon, 6 Jan 2025 17:17:42 +0000 Subject: [PATCH 4/6] Linting to fix failing test --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 845513d..e5ea219 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,6 +66,7 @@ make spell_check ``` or: + ```sh docker run --rm -ti -v $(pwd):/workdir tmaier/markdown-spellcheck:latest \ --report --ignore-numbers --ignore-acronyms "**/*.md" From 8953244193167e275aa4a0d2d38c3cffc078208a Mon Sep 17 00:00:00 2001 From: David Winterbottom Date: Wed, 8 Jan 2025 15:16:35 +0000 Subject: [PATCH 5/6] Rejig the contributing guide This commit: - Ensures all contributing instructions now work - Upgrades Prettier to v3.2.5 (and fixes the related issues) --- .circleci/config.yml | 7 +-- .gitignore | 1 + .prettierignore | 5 +++ .spelling | 2 + CONTRIBUTING.md | 103 ++++++++++++++++++------------------------- makefile | 9 +++- 6 files changed, 64 insertions(+), 63 deletions(-) create mode 100644 .gitignore diff --git a/.circleci/config.yml b/.circleci/config.yml index c0b9893..7bd36a6 100644 --- a/.circleci/config.yml +++ b/.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: diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..cdb93cd --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.python-version diff --git a/.prettierignore b/.prettierignore index 1d53451..e7785d1 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,3 +1,8 @@ *.yml *.yaml *.json +.pytest_cache/ +.circleci/ +.prettierignore +.spelling +makefile diff --git a/.spelling b/.spelling index 6e89038..8bec330 100644 --- a/.spelling +++ b/.spelling @@ -17,6 +17,8 @@ sendgrid stylelint vscode webtest +homebrew +markdownlint # Terminology ORM-constructs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e5ea219..ff58bda 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,19 +1,23 @@ # Contributing -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 PR. +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. ## Installation -You'll need a few tools to make and test your changes before pushing them to a PR. +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. ### Prettier -All Markdown should be formatted with [Prettier](https://prettier.io/) version 3.1 -Install with: +Ensure [Prettier](https://prettier.io/) version 3.2.5 is installed. It can be installed with: -```sh -npm install -g prettier@3.1 -``` + npm install -g prettier@3.2.5 + +Verify the installed version is correct with: + + prettier --version Once installed, ensure your editor runs Prettier on a pre-save hook: @@ -21,91 +25,72 @@ Once installed, ensure your editor runs Prettier on a pre-save hook: - [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 -### Pytest +Ensure you have Docker installed. Mac users can [install from Homebrew](https://formulae.brew.sh/formula/docker). -## Development +### Python tooling -### Run CI tests locally +Ensure you have a Python 3.11 virtual environment created for this project and +Python packages have been installed with `make install`. -If your changes include Markdown, be aware that Markdown code in this repo must pass several static analysis tests. Before pushing to GitHub, run +There are various ways of doing +this - here is one that uses `pyenv` and `pyenv-virtualenvwrapper`: ```sh -make ci +pyenv local 3.11.4 # Match the version in `.circleci/config.yml` +mkvirtualenv conventions +make install ``` -to run these checks. - -### 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, 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. - -### Spelling +## Development -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. +### Formatting -To run the spell-test locally run: +Markdown should be formatted with Prettier using the configuration in +`.prettierrc.yaml`. Verify this with: ```sh -make spell_check +make prettier_check ``` -or: +### Linting + +Markdown should conform to the Markdownlint rules declared in +`.markdownlint.yaml`. Verify this with: ```sh -docker run --rm -ti -v $(pwd):/workdir tmaier/markdown-spellcheck:latest \ - --report --ignore-numbers --ignore-acronyms "**/*.md" +make markdownlint ``` -Add exceptions to the custom dictionary in `.spelling`. - -### Linting - -Markdown files are linted by -[`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli). +### Spelling -To run the linting locally run: +Markdown must pass a spell-check. Verify this with: ```sh -docker run -i --rm -v `pwd`:/work tmknom/markdownlint:0.33.0 +make spell_check ``` -or, if installed on your host OS, run: +Spelling exceptions are held in `.spelling`. -```sh -markdownlint . -``` +### Commit messages -or: +Git commit subjects must: -```sh -make markdownlint -``` +- Be no longer than 70 characters. +- Start with a capital letter. +- Not end with a full stop. -Configuration for the enforced rules is in `.markdownlint.yaml`. +Further, PR branches should rebase off `main` to incorporate upstream +changes; don't merge `main` into your branch. -Many linting issues can be fixed by running: +These rules are checked using Pytest in CI. Verify conformance with: ```sh -markdownlint --fix . +make test ``` -## Preview rendered pages +### Preview rendered pages You can use [`grip`](https://github.com/joeyespo/grip) to render Github-flavour markdown files. Install with: diff --git a/makefile b/makefile index 7c92d18..1f8c0be 100644 --- a/makefile +++ b/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 From 6b2068f8d1c67ca0aedbee651ac2d86649b62383 Mon Sep 17 00:00:00 2001 From: ioreka Date: Thu, 9 Jan 2025 20:12:10 +0000 Subject: [PATCH 6/6] Add clarification about Docker installation While troubleshooting the docker daemon issues in the spelling and linting commands, I discovered a missing step for users who (like me) did not have Docker already installed (https://stackoverflow.com/questions/44084846/cannot-connect-to-the-docker-daemon-on-macos). The easiest docs amend was to advise installing the app and having an account. --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff58bda..0ae5671 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,15 +27,15 @@ Once installed, ensure your editor runs Prettier on a pre-save hook: ### Docker -Ensure you have Docker installed. Mac users can [install from Homebrew](https://formulae.brew.sh/formula/docker). +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). ### Python tooling Ensure you have a Python 3.11 virtual environment created for this project and Python packages have been installed with `make install`. -There are various ways of doing -this - here is one that uses `pyenv` and `pyenv-virtualenvwrapper`: +There are various ways of doing this - here is one that uses `pyenv` and `pyenv-virtualenvwrapper`: ```sh pyenv local 3.11.4 # Match the version in `.circleci/config.yml`