diff --git a/.gitignore b/.gitignore index 0bc7dc0b9..d6a58b88b 100644 --- a/.gitignore +++ b/.gitignore @@ -45,6 +45,7 @@ zope.interface-*.egg /.tox/ /docs/_build/ /coverage.xml +/.pre-commit-config.local.yaml /.hypothesis/ /eliot.log /misc/python3/results.xml diff --git a/Makefile b/Makefile index d80018438..e465ee30e 100644 --- a/Makefile +++ b/Makefile @@ -32,6 +32,11 @@ default: .PHONY: install-vcs-hooks ## Install the VCS hooks to run linters on commit and all tests on push install-vcs-hooks: .git/hooks/pre-commit .git/hooks/pre-push +.PHONY: uninstall-vcs-hooks +## Remove the VCS hooks +uninstall-vcs-hooks: .tox/create-venvs.log + "./$(dir $(<))py36/bin/pre-commit" uninstall || true + "./$(dir $(<))py36/bin/pre-commit" uninstall -t pre-push || true .PHONY: test ## Run all tests and code reports @@ -196,7 +201,7 @@ clean: rm -f *.pkg .PHONY: distclean -distclean: clean +distclean: clean uninstall-vcs-hooks rm -rf src/*.egg-info rm -f src/allmydata/_version.py rm -f src/allmydata/_appname.py diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst index dbd7d6438..ab9b5a743 100644 --- a/docs/INSTALL.rst +++ b/docs/INSTALL.rst @@ -288,15 +288,6 @@ result in a "all tests passed" mesage:: py27: commands succeeded congratulations :) -You may also install VCS/git hooks to run linters and code checks to catch -common errors before each commit and to run the full self-test suite to find -less obvious regressions before each push to a remote. Not that running the -full self-test suite takes several minutes to expecting pushing to take some -time. If you can't or don't want to wait for the hooks in some cases, use -the ``--no-verify`` option to ``git commit ...`` or ``$ git push ...``:: - - $ make install-vcs-hooks - Common Problems =============== diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index e2b438187..2d26e68a4 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -5,40 +5,85 @@ Developer Guide Pre-commit Checks ----------------- -This project is configured for use with `pre-commit `_ to perform some static code analysis checks. By default, pre-commit behavior is disabled. To enable pre-commit in a local checkout, first install pre-commit (consider using `pipx `_), then install the hooks with ``pre-commit install``. +This project is configured for use with `pre-commit`_ to install `VCS/git hooks`_ which +perform some static code analysis checks and other code checks to catch common errors +before each commit and to run the full self-test suite to find less obvious regressions +before each push to a remote. For example:: - tahoe-lafs $ pre-commit install + tahoe-lafs $ make install-vcs-hooks + ... + + ./.tox//py36/bin/pre-commit install --hook-type pre-commit pre-commit installed at .git/hooks/pre-commit + + ./.tox//py36/bin/pre-commit install --hook-type pre-push + pre-commit installed at .git/hooks/pre-push tahoe-lafs $ python -c "import pathlib; pathlib.Path('src/allmydata/tabbed.py').write_text('def foo():\\n\\tpass\\n')" tahoe-lafs $ git add src/allmydata/tabbed.py tahoe-lafs $ git commit -a -m "Add a file that violates flake8" - flake8...................................................................Failed - - hook id: flake8 + ... + codechecks...............................................................Failed + - hook id: codechecks - exit code: 1 + GLOB sdist-make: ./tahoe-lafs/setup.py + codechecks inst-nodeps: ... + codechecks installed: ... + codechecks run-test-pre: PYTHONHASHSEED='...' + codechecks run-test: commands[0] | flake8 src static misc setup.py src/allmydata/tabbed.py:2:1: W191 indentation contains tabs + ERROR: InvocationError for command ./tahoe-lafs/.tox/codechecks/bin/flake8 src static misc setup.py (exited with code 1) + ___________________________________ summary ____________________________________ + ERROR: codechecks: commands failed + ... To uninstall:: - tahoe-lafs $ pre-commit uninstall + tahoe-lafs $ make uninstall-vcs-hooks + ... + + ./.tox/py36/bin/pre-commit uninstall pre-commit uninstalled + + ./.tox/py36/bin/pre-commit uninstall -t pre-push + pre-push uninstalled +Note that running the full self-test suite takes several minutes so expect pushing to +take some time. If you can't or don't want to wait for the hooks in some cases, use the +``--no-verify`` option to ``$ git commit ...`` or ``$ git push ...``. Alternatively, +see the `pre-commit`_ documentation and CLI help output and use the committed +`pre-commit configuration`_ as a starting point to write a local, uncommitted +``../.pre-commit-config.local.yaml`` configuration to use instead. For example:: -Some find running linters on every commit to be a nuisance. To avoid the checks triggering during commits, but to check before pushing to the CI, install the hook for pre-push instead:: - - tahoe-lafs $ pre-commit install -t pre-push + tahoe-lafs $ ./.tox/py36/bin/pre-commit --help + tahoe-lafs $ ./.tox/py36/bin/pre-commit instll --help + tahoe-lafs $ cp "./.pre-commit-config.yaml" "./.pre-commit-config.local.yaml" + tahoe-lafs $ editor "./.pre-commit-config.local.yaml" + ... + tahoe-lafs $ ./.tox/py36/bin/pre-commit install -c "./.pre-commit-config.local.yaml" -t pre-push pre-commit installed at .git/hooks/pre-push tahoe-lafs $ git commit -a -m "Add a file that violates flake8" [3398.pre-commit 29f8f43d2] Add a file that violates flake8 1 file changed, 2 insertions(+) create mode 100644 src/allmydata/tabbed.py tahoe-lafs $ git push - flake8...................................................................Failed - - hook id: flake8 + ... + codechecks...............................................................Failed + - hook id: codechecks - exit code: 1 + GLOB sdist-make: ./tahoe-lafs/setup.py + codechecks inst-nodeps: ... + codechecks installed: ... + codechecks run-test-pre: PYTHONHASHSEED='...' + codechecks run-test: commands[0] | flake8 src static misc setup.py src/allmydata/tabbed.py:2:1: W191 indentation contains tabs + ERROR: InvocationError for command ./tahoe-lafs/.tox/codechecks/bin/flake8 src static misc setup.py (exited with code 1) + ___________________________________ summary ____________________________________ + ERROR: codechecks: commands failed + ... error: failed to push some refs to 'github.com:jaraco/tahoe-lafs.git' + + +.. _`pre-commit`: https://pre-commit.com +.. _`VCS/git hooks`: `pre-commit`_ +.. _`pre-commit configuration`: ../.pre-commit-config.yaml