ci: Add pre-commit configs

[jidicula]

Checklist

• I've given this PR a concise, self-descriptive, and meaningful title
• I've linked relevant issues in the PR body
• I've applied the relevant labels to this PR
• I've added relevant tests for my contribution
• I've updated the documentation and/or added correct docstrings
• I've assigned a reviewer

Description

Why this change was necessary
We want to enforce file size limits on commits to ensure contributors
don't accidentally commit massive files to the repo and pollute the
history. This should be checked both locally and on GitHub.

What this change does

• Adds pre-commit as an optional dev dependency
• Adds pre-commit hooks for YAML check, merge conflict string
  check, AST check, and large file (>500kb) check
• Adds GitHub Action to run above pre-commit checks on each PR and
  push to master
• Updates documentation to instruct contributors to install dev dependencies

Additional context/notes/links

• https://github.com/pre-commit/pre-commit-hooks#check-added-large-files
• https://pre-commit.com

Linked issues

Resolves #199

[po09i]

Are the local hooks always run when we locally commit something or we need to manually run pre-commit to check?

[jidicula]

Once the project has been reinstalled with pip install -e ".[docs,dev]" and you've run pre-commit install once, the hooks will run automatically when you locally commit something.

[po09i]

Awesome, I'm scared to test it but if you have then it LGTM!

[jidicula]

@shimming-toolbox/editors once this PR is closed, please run pip install -e ".[docs,dev]", then run pre-commit install.

[joshuacwnewton]

Cross-referencing the related issues on sister projects to get that sweet, sweet GH auto-linking UI magic:

• Integrate pre-commit hooks to ban large files spinalcordtoolbox/spinalcordtoolbox#2705, Limit file size on commit spinalcordtoolbox/spinalcordtoolbox#3100
• Limit file size on commit ivadomed/ivadomed#583
• Limit file size on commit neuropoly/data-management#43

[vasudev-sharma]

Inspired by this PR, we're implementing the same feature in another sister project (AxonDeepSeg) see here.

The pre-commit hook in this PR requires the developer/contributor to do the mandatory step pre-commit install so that the checks are being caught locally.

There might be instances where the developer might forget this step and this would lead to the checks being skipped locally.

In order to avoid this, for this, in the PR axondeepseg/axondeepseg#464, we are thinking to do add pre-commit install in the build script (setup.py) as a post-install step via setuptools.

I wish to know did you consider this option for installing pre-commit hooks?

1. If yes, may I know why you didn't plan on keeping it?

2. If no, then may I know your thoughts on this?

[jidicula]

I wish to know did you consider this option for installing pre-commit hooks?

1. If yes, may I know why you didn't plan on keeping it?
2. If no, then may I know your thoughts on this?

I actually didn't know this was an option! It looks like it's viable, with the only caveat that it creates a bit of dependence on setup.py magic. Just remember to attempt triggering it only if the dev extra is the build option. My other worry about setup.py dependence is that it makes shifting to the recommended pyproject.toml dependency specification a bit harder - hopefully PSF comes up with something that replicates that functionality.

[vasudev-sharma]

Thanks @jidicula for your valuable inputs.