docs: links to contributing.md pre-commit instructions, added isort

nci · Oct 19, 2023 · 21da685 · 21da685
1 parent 0fbf045
commit 21da685
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 10 deletions.
diff --git a/docs/codingpractises.md → docs/coding_practices.md b/docs/codingpractises.md → docs/coding_practices.md
@@ -1,14 +1,17 @@
-# Coding Practises
+# Coding Practices
 
-The [contributing.md](Contributing Guide) provides (among other things) guidance on the workflows and general expectations associated with contributing a code change to `scores`. This document eschews some of the context to focus on specifying technical information needed when developing code for `scores`.
+The [Contributing Guide](contributing.md) provides (among other things) guidance on the workflows and general expectations associated with contributing a code change to `scores`. This document eschews some of the context to focus on specifying technical information needed when developing code for `scores`.
 
 # Expectations:
 
-1. Black has been run over the code
-2. Pylint has been run and there are zero lint issues
-3. mypy has been run and there are zero mypy issues
-4. Test coverage is 100%
-5. All scores/metrics have a demonstration notebook
+1. `black` and `isort` fixers have been run over the code
+2. `pylint` and `mypy` linters have been run with no errors
+3. Test coverage is 100%
+4. All scores/metrics have a demonstration notebook
+
+See the [contributing docs](contributing.md) for a development overview and [`pre-commit` configuration](contributing.md#pre-commit) for automating these steps.
+
+> Note: Please refer to [pyproject.toml dev dependencies](../pyproject.toml#L30) for pinned versions of linters and fixers for this project.
 
 # Type Hinting
 

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -88,15 +88,15 @@ python -m build
 pip install dist/<my_latest_package>.whl
 ```
 
-### Setup `pre-commit` (Optional)
+### Setup `pre-commit` (Optional) <a name="pre-commit"></a>
 
 To automate linter and fixer checks this project uses `pre-commit` which is setup to execute after every local commit. This ensures that code standards are flagged at the development stage rather than in the project CI/CD pipeline. Although it is optional we highly recommended to use the tool before pushing changes to the remote.
 
 ```bash
 pre-commit install -t pre-commit -t pre-push
 ```
 
-### Coding Practises
+### Coding Practices
 
 Pylint and black should be used at all times to ensure a consistent approach to coding. Isort should be used for the ordering of import statements. All merge requests will be checked prior to acceptance. The project will include configuration files which may be used to capture any overrides to convention that may be adoped.
 
@@ -152,4 +152,3 @@ A science review should answer the following questions:
 3. Does the implementation look correct if read at face value (i.e. detailed knowledge of libraries not required)?
 4. Are any issues of scientific interpretation explained (i.e. if multiple mathematical interpretations of a method are reasonable, is this made clear)?
 5. Are the examples contained in the tutorial well-explained and relevant?
-