Troubleshooting pre-commit failures
Many common pre-commit test failures related to formatting can be
automatically fixed by adding a comment on a pull request that says
pre-commit.ci autofix (like in
This comment will lead to a new commit to the pull request branch that
applies the automatic fixes made by the different pre-commit hooks.
After doing this, please do a
git pull in your clone of
PlasmaPy’s repository to pull back the auto fixes to your computer.
The following sections contain suggestions for how to fix pre-commit
failures that were not corrected by commenting
on the issue.
Make sure all other tests are passing before manually fixing pre-commit test failures. Failures from pre-commit should generally be fixed after making sure all other tests are passing.
Every issue detected by ruff corresponds to a specific lint rule. For
example, lint rule F401 removes unused
import statements. If you
encounter a confusing ruff rule, search ruff’s documentation page on
rules for the rule code and click on its name for more information.
Problems flagged by C901 occur when a function is too complex (i.e., when it contains heavily nested control flow), which makes code much more difficult to maintain.
Reduce complexity by breaking up complicated functions into short functions that do exactly one thing with no side effects.
Disabling a ruff rule
While ruff usually suggests improvements, there will occasionally be
times where a departure from a ruff rule is (at least temporarily)
justified. In these cases, we can append a
# noqa <rule-codes>
comment to the end of a line (where
<rule-codes> is replaced
with the corresponding ruff rule codes, and
noqa stands for “no
quality assurance”) to tell ruff to ignore that error on that line.
def overly_complicated_function(): # noqa: C901, PLR0912, PLR0915 """A function with 100+ lines of code and lots of if/else branches."""
When writing new code, it is almost always better to refactor the
code to remove the error rather than add a
noqa comment. In the
above example, it would be better to refactor an overly complicated
function into multiple short functions that do exactly one thing with
no side effects so that the code is easier to understand, modify, and
maintain. We should only add
noqa statements when we have a good
PlasmaPy uses codespell to find typos in source code. Rather than checking if each word matches a dictionary entry, codespell tries to match words to a set of common misspellings. This approach greatly reduces the number of false positives, but will occasionally miss some uncommon misspellings.
If you encounter a false positive with codespell, add it to
Using pre-commit locally
pre-commit checks are performed on GitHub for every pull request, but it is also possible to set up pre-commit locally.
To enable pre-commit on your computer:
If you use a Conda or virtual environment for developing PlasmaPy, activate it (i.e., with
conda activate plasmapy-dev).
Make sure that pre-commit is installed to your Python environment by running:
py -m pip install pre-commit
python -m pip install pre-commit
python -m pip install pre-commit
Navigate to the
PlasmaPy/directory that contains your clone of PlasmaPy’s repository. For example, if you cloned PlasmaPy into the
~/repos/directory, then run:
Enable pre-commit with:
Changes to the workflow
Once pre-commit has been installed for a repository, pre-commit will run every time you try to commit a change.
If any pre-commit checks fail, or if pre-commit changes any files, it
will be necessary to redo
git add on the changed files and
git commit once again.
To commit a change without running pre-commit, use the
flag (short for
--no-verify) with git.
To run pre-commit on all files, use
pre-commit run --all-files