Skip to content

Pre-commit

Pre-commit is PROCESS' way of ensuring all code pushed to our repository is of a certain quality and style. One common style ensures PROCESS can be easily navigated and understood by all users. It also reduces the "diffs" when reviewing code changes as often small style changes (such as the addition of a new-line) will litter the "diffs" and make reviewing harder.

pre-commit website

Pre-commit works on staged files (ie those that have been git added) after you issue the git commit command but before the commit is actually made. If any pre-commit job failed then the commit will not be made. On a failure, one of two things can happen:

  1. Pre-commit plugins will rectify the mistakes made. This will happen with code formatters (whose job it is to edit your files to the correct style). The files the plugins have changed can then be git added again and the git commit command re-issued.
  2. A pre-commit plugin will identify the mistake but will NOT fix it. This could happen with ruff which is a linter and warns of code mistakes but does not correct them. You will need to fix these mistakes manually. Now, the changed files can be git added and the git commit command re-issued.

VSCode GUI users

On the VSCode GUI, you will see that files pre-commit modifies will change from green as there are changes that need to made. Follow your usual workflow to re-add these files and re-do the commit as usual.

Tip

I would advise you become familiar with the What does pre-commit check for? section of this document. This will allow you to understand whether a mistake has been automatically fixed or not.

Installation

When running cmake --build build/ pre-commit should have been installed automatically. This can be tested by typing

pre-commit -h

If pre-commit is not installed, then it can be installed by:

python3 -m pip install pre-commit

For developers of PROCESS

pre-commit install

will install pre-commit as a Git pre-commit hook. When pre-commit is a hook, it will run on all of the files you have changed before allowing a commit -- if any changes are identified, they will be fixed and you will need to re-add the files that pre-commit has changed.

Pre-commit Python version

It is important then pre-commit is running on Python 3.8. Any other Python version may produce code formatted in such a way that our CI system rejects your code.

Adding two files

Consider that two files are being git added. One of the files, foo.py has stylistic changes which ruff objects to.

> git add foo.py bar.py
> git commit -m "Adding foo and bar"
    Trim Trailing Whitespace.................................................Passed
    Check for merge conflicts................................................Passed
    Debug Statements (Python)................................................Passed
    ruff.....................................................................Failed
        - hook id: ruff-format
        - exit code: 1
        - files were modified by this hook

        Fixing foo.py
    Format YAML files....................................(no files to check)Skipped

> git add foo.py # since ruff has modified foo.py
> git commit -m "Adding foo and bar"

Pre-commit and the quality CI stage

The Process continuous integration system (used to check Process builds and passes tests) also has a quality stage. This is where several jobs will run to ensure the quality of your code. If all your commits pass through pre-commit, then these jobs should not fail as your code will be of a high quality.

Using ruff with VSCode

Although not required, the ruff VSCode extension will ensure that all the Python files you save will be ruff-compliant and, as such, won't need to modified by pre-commit.

Open or create the file .vscode/settings.sh and add/modify the following settings: 

{
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true
    }
}

What does pre-commit check for?

General style on all files

Pre-commit performs a few checks on each and every file you add, regardless of type.

  • end-of-file-fixer will check that each file ends with exactly one new line. This plugin will automatically fix any mistakes it finds.
  • trailing-whitespace will check that there is no excess whitespace (spaces or tabs) at the end of any line. This plugin will automatically fix any mistakes it finds.
  • check-merge-conflict checks that all merge conflict's have been resolved. This plugin will NOT automatically fix any mistakes it finds.

Python checks

Because Process is becoming increasingly Pythonised, pre-commit performs many Python style checks.

  • ruff formats and lints code. It will identify formatting and stylistic errors in Python code. This plugin will automatically fix any mistakes it finds.
  • check-docstring-first will check that a function/class docstring comes before any of the body (ie the docstring must be at the top). This plugin will NOT automatically fix any mistakes it finds.
  • debug-statements will check that debug statements (those using the built-in pdb module) have been removed. This plugin will NOT automatically fix any mistakes it finds.

Other checks

  • yamlfmt formats YAML code (similar to what ruff does for Python code). This plugin will automatically fix any mistakes it finds.