Consider Using Pre-Commit

[O957]

This issue covers considerations for using the tool https://pre-commit.com/ (a tool for linting and formatting, across tools, before committing).

Git hook scripts are useful for identifying simple issues before submission to code review. We run our hooks on every commit to automatically point out issues in code such as missing semicolons, trailing whitespace, and debug statements. By pointing these issues out before code review, this allows a code reviewer to focus on the architecture of a change while not wasting time with trivial style nitpicks.

As we created more libraries and projects we recognized that sharing our pre-commit hooks across projects is painful. We copied and pasted unwieldy bash scripts from project to project and had to manually change the hooks to work for different project structures.

There are many hooks supported by pre-commit. For this repository, the ruff Python linter and formatter (e.g. for automatically abiding by PEP-8 standards, https://peps.python.org/pep-0008/) might especially be useful (in addition to the typos hook, which I used to find the misspellings in #44 ).

Example .pre-commit-config.yaml File

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
    -   id: check-added-large-files
        args: ["--maxkb=10000"]
    -   id: check-ast
    -   id: check-case-conflict
    -   id: check-docstring-first
    -   id: check-yaml
        args: ["--allow-multiple-documents"]
    -   id: check-toml
    -   id: end-of-file-fixer
    -   id: mixed-line-ending
    -   id: name-tests-test
        args: ["--pytest-test-first"]
    -   id: pretty-format-json
        args: ["--autofix", "--no-sort-keys",  "--indent", "4"]
    -   id: trailing-whitespace
# lint markdown formatting
-   repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.48.0
    hooks:
    -   id: markdownlint
        args: [--fix]
# adhere to PEP-8 and best Python practice
-   repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.15.12
    hooks:
    -   id: ruff-check
        args: ["--fix"]
    -   id: ruff-format
# find dead Python code
-   repo: https://github.com/jendrikseipp/vulture
    rev: v2.16
    hooks:
    -   id: vulture
# ensure github actions adhere to best practice
-   repo: https://github.com/rhysd/actionlint
    rev: v1.7.12
    hooks:
    -   id: actionlint
# detect misspellings in code
-   repo: https://github.com/crate-ci/typos
    rev: v1
    hooks:
    -   id: typos
        args: ["--force-exclude"]

Example Pre-Commit Output (Local Run)

I'd be happy to create a PR for this. Feel free to assign me. If assigned, I will change the name of the issue to "Add Pre-Commit And Default Hooks". The default hooks can be sorted out in the PR.

Subjectively, pre-commit has been a favorite of mine (given its lightness and utility) among the tools I've learned about in the last several years.

The workflow is, for a repository, pre-commit install. Then one can manually run pre-commit run --all-files (or simply commit and have pre-commit run). https://pre-commit.ci/ exists as well, which will automatically fix fixable changes.