diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37de0fc5..6bcd106f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ this case, the [Apache Software License v2](LICENSE). To contribute to Sygnal, ensure you have Python 3.7 or newer and then run: -``` +```bash python3 -m venv venv ./venv/bin/pip install -e . ./venv/bin/pip install -U black flake8 isort mypy mypy-zope tox @@ -18,11 +18,11 @@ python3 -m venv venv This creates an isolated virtual Python environment ("virtualenv") just for use with Sygnal, then installs Sygnal along with its dependencies, and lastly -installs a handful of useful tools +installs a handful of useful tools Finally, activate the virtualenv by running: -``` +```bash source ./venv/bin/activate ``` @@ -37,7 +37,7 @@ the virtualenv. To make sure everything is working as expected, run the unit tests: -``` +```bash tox -e py ``` @@ -88,27 +88,23 @@ Sygnal follows the [Synapse code style]. Many of the conventions are enforced by scripts which are run as part of the [continuous integration system](#continuous-integration-and-testing). -To help check and fix adherence to the code style, you can run `scripts-dev/lint.sh` -locally. You'll need Python 3.7 or later, and to install a number of tools: - -``` -# Install the dependencies -pip install -U black flake8 isort mypy mypy-zope - -# Run the linter script -./scripts-dev/lint.sh -``` +To help check and fix adherence to the code style, you can run `tox` +locally. You'll need Python 3.7 or later, and a virtual environment configured and +active: -**Note that the script does not just test/check, but also reformats code, so you -may wish to ensure any new code is committed first**. +```bash +# Activate the virtual environment +source ./venv/bin/activate -By default, this script checks all files and can take some time; if you alter -only certain files, you might wish to specify paths as arguments to reduce the -run-time: +# Run the code style check +tox -e check_codestyle +# Run the types check +tox -e check_types ``` -./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder -``` + +These commands will consider the paths and files related to the project (i.e. +everything in `sygnal/` and in `tests/` as well as the `setup.py` file). Before pushing new changes, ensure they don't produce linting errors. Commit any files that were corrected. diff --git a/changelog.d/193.doc b/changelog.d/193.doc new file mode 100644 index 00000000..5e48a1df --- /dev/null +++ b/changelog.d/193.doc @@ -0,0 +1 @@ +Update CONTRIBUTING.md to specify how to run code style and type checks with Tox, and add formatting to code block samples. diff --git a/changelog.d/193.misc b/changelog.d/193.misc new file mode 100644 index 00000000..3f50574f --- /dev/null +++ b/changelog.d/193.misc @@ -0,0 +1 @@ +Updated Tox to run in the installed version of Python (instead of specifying Python 3.7) and to consider specific paths and folders while running checks, instead of the whole repository (potentially including unwanted files and folders, e.g. the virtual environment). diff --git a/scripts-dev/lint.sh b/scripts-dev/lint.sh deleted file mode 100755 index f05d7e73..00000000 --- a/scripts-dev/lint.sh +++ /dev/null @@ -1,26 +0,0 @@ -#!/bin/sh -# -# Runs linting scripts over the local Sygnal checkout -# isort - sorts import statements -# black - opinionated code formatter -# flake8 - lints and finds mistakes -# mypy - checks types - -set -e - -if [ $# -ge 1 ] -then - files=$* -else - files="sygnal tests" -fi - -echo "Linting these locations: $files" -echo " ===== Running isort ===== " -isort $files -echo " ===== Running black ===== " -black $files -echo " ===== Running flake8 ===== " -flake8 $files -echo " ===== Running mypy ===== " -mypy $files diff --git a/tox.ini b/tox.ini index 51e8d105..48d976e6 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -envlist = py37, check_codestyle, check_types +envlist = py, check_codestyle, check_types [testenv] @@ -22,13 +22,13 @@ deps = black==19.10b0 isort~=5.0 commands = - flake8 . - black --check --diff . - isort --check-only --diff . + flake8 sygnal/ tests/ setup.py + black --check --diff sygnal/ tests/ setup.py + isort --check-only --diff sygnal/ tests/ setup.py [testenv:check_types] deps = mypy==0.780 mypy-zope==0.2.7 commands = - mypy . + mypy sygnal/ tests/ setup.py