Complete a first pass of updated contributing guidelines.

CONTRIBUTING.md

@@ -37,8 +37,66 @@ Ideally python code should be:
 * Broken up into small clear testable functions.
 * Documented with docstrings (For conventions see below).
 * Type hinted
-* Covered by unit tests
+* Covered by unit tests (using [pytest](https://docs.pytest.org))
 
 The server code is going through significant flux during the transition from v2 to v3, so currently our test coverage is being rebuilt and type checking does not yet pass.
 
+[Ruff](https://docs.astral.sh/ruff/) is used both for linting and formatting, the codebase. Our custom linter rules are in out `pyproject.toml`. As we improve the codebase more rules are being added to the linter, see `ruff-increased-checking.toml` for checks that we plan to get passing.
 
+Run `ruff format` to format the code in a way that will pass on our CI.
+
+Run `ruff check` to check for linter errors.
+
+To check your code before each commit we recommend putting the following script in tour `.git/hooks` directory with the filename `pre-commit`.
+
+
+```python
+#!/bin/bash
+
+set -e
+
+function angrymessage()
+{
+    RED='\033[1;31m'
+    NC='\033[0m' # No Color
+    printf "\n${RED}Not committing as ruff failed${NC}\n\n"
+}
+
+trap angrymessage ERR
+
+ruff format --check
+ruff check
+```
+
+
+## Docstrings conventions.
+
+For docstrings we write docstrings in [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), and process them with [pydoctor](https://pydoctor.readthedocs.io/).
+
+For function arguments, return values, and exceptions we use the following style recognised by reStructuredText:
+
+```python
+def a_function(arg1: str, arg2: int) -> tuple[float, int]:
+    """
+    A one sentence summary, in imperative mood, ending with punctuation.
+
+    More detail after a blank line. This could be a whole paragraph.
+
+    When referring to ``code`` in reStructuredText used double backticks
+
+    :param arg1: This is the first argument, we can say everything we need to about it.
+        If the text wrapas ont a new line this line is indented.
+    :param arg2: This is the second argument.
+
+    :returns: Say what it returns without anything within the colons. If returning
+        multiple values a bulleted list is a good idea just make sure:
+
+        * It is indented to 1 level in
+        * There is a blank line before the bullets
+        * The bullet points are ``*`` not ``-``
+    """
+```
+
+The linter rules we use for docstrings are defined by [pydocstyle](https://docs.astral.sh/ruff/rules/#pydocstyle-d). We do not use rules D203, D213, D400.
+
+The documentation generated by pydoctor from docstrings can be viewed in any merge request (if the CI pipeline has passed) using the "View App" button.