Add pre-commit

This merge requests implements #41 (closed).

We use pre-commit to automatically format our code-base before any git commits are made client-side, i.e. on the developer's working environment and not on the remote Git repository (such as GitLab or GitHub). This has the benefit of quickly catching developer errors, ensuring that all code complies with shared standards across the repository, and minimising excessive commit history focused specifically on auto-formatting (server-side hooks are possible but may introduce an additional commit as the developer would have to first commit before pushing).

When a git commit command is called after staging files, pre-commit will be run before the commit is finalised. If the pre-commit checks fail, the commit will be aborted. Additionally, if any changes ARE made to your files according to the rules configured in .pre-commit-config.yaml, files will need to be re-staged as they would have been modified since the initial file staging procedure (git add).

See the documentation at pre-commit for more information, and this page describing client-side and server-side git hooks more generally.

To do the initial setup, activate your installed Python virtual environment and run the following commands:

# pip install pre-commit  # this is already in requirements.txt, and so not required
pre-commit install
pre-commit run --all-files  # by default pre-commit only runs on git staged files

The merge request proposed in patrick.clearwater/spiir-scripts!8 also automatically installs pre-commit into the top level spiir git repository when running bash build-spiir.sh build-spiir.

Note that adding clang-format and Black (#40) to pre-commit requires version 2.9.2, which is a version of pre-commit only available in Python 3. We can implement pre-commit for yapf Python2.7 only, and then upgrade to include both clang and Black after the Python 3 transition.

See:

• clang-format:
  • Our Python2.7 pre-commit version is 1.20.1, but clang-format requires: minimum_pre_commit_version: '2.9.2'
• Black:
  • Black requires a Python virtual environment of >=3.6 to run.
  • Black can technically format Python2.7 code in a Python3 virtual environment, but we don't want to use this approach due to the complexities of Python module management on OzStar (our main development environment).