@@ -51,3 +51,88 @@ All interactions for this project are covered by the
51
51
`PSF Code of Conduct <https://www.python.org/psf/codeofconduct/ >`_. Everyone is
52
52
expected to be open, considerate, and respectful of others no matter their
53
53
position within the project.
54
+
55
+
56
+ Run pre-commit linting locally
57
+ ------------------------------
58
+
59
+ You can run this repo's basic linting suite locally,
60
+ either on-demand, or automatically against modified files
61
+ whenever you commit your changes.
62
+
63
+ They are also run in CI, so you don't have to run them locally, though doing
64
+ so will help you catch and potentially fix common mistakes before pushing
65
+ your changes and opening a pull request.
66
+
67
+ This repository uses the `pre-commit <https://pre-commit.com/ >`_ tool to
68
+ install, configure and update a suite of hooks that check for
69
+ common problems and issues, and fix many of them automatically.
70
+
71
+ If your system has ``make `` installed, you can run the pre-commit checkers
72
+ on the full repo by running ``make lint ``. This will
73
+ install pre-commit in the current virtual environment if it isn't already,
74
+ so make sure you've activated the environment you want it to use
75
+ before running this command.
76
+
77
+ Otherwise, you can install pre-commit with
78
+
79
+ .. code-block :: console
80
+
81
+ python -m pip install pre-commit
82
+
83
+ (or your choice of installer), and then run the hooks on all the files
84
+ in the repo with
85
+
86
+ .. code-block :: console
87
+
88
+ pre-commit run --all-files
89
+
90
+ or only on any files that have been modified but not yet committed with
91
+
92
+ .. code-block :: console
93
+
94
+ pre-commit run
95
+
96
+ If you would like pre-commit to run automatically against any modified files
97
+ every time you commit, install the hooks with
98
+
99
+ .. code-block :: console
100
+
101
+ pre-commit install
102
+
103
+ Then, whenever you ``git commit ``, pre-commit will run and report any issues
104
+ it finds or changes it makes, and abort the commit to allow you to check,
105
+ and if necessary correct them before committing again.
106
+
107
+
108
+ Check and fix PEP spelling
109
+ --------------------------
110
+
111
+ To check for common spelling mistakes in your PEP and automatically suggest
112
+ corrections, you can run the codespell tool through pre-commit as well.
113
+
114
+ Like the linters, on a system with ``make `` available, it can be installed
115
+ (in the currently-activated environment) and run on all files in the
116
+ repository with a single command, ``make spellcheck ``.
117
+
118
+ For finer control or on other systems, after installing pre-commit as in
119
+ the previous section, you can run it against only the files
120
+ you've modified and not yet committed with
121
+
122
+ .. code-block :: console
123
+
124
+ pre-commit run --hook-stage manual codespell
125
+
126
+ or against all files with
127
+
128
+ .. code-block :: console
129
+
130
+ pre-commit run --all-files --hook-stage manual codespell
131
+
132
+ **Note **: While fixing spelling mistakes as part of more substantive
133
+ copyediting and proofreading of draft and active PEPs is okay,
134
+ we generally advise against PRs that simply mass-correct minor typos on
135
+ older PEPs that don't significantly impair meaning and understanding,
136
+ as these tend to create a fairly high level of noise and churn for
137
+ PEP readers, authors and editors relative to the amount of practical value
138
+ they provide.
0 commit comments