diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cd13e6962a63..e81dc42e17c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,14 +24,23 @@ it takes a bit longer. For more details, read below. ## Preparing the environment -To reformat the code, check for common problems, and -run the tests, it can be useful to prepare a -[virtual environment](https://docs.python.org/3/tutorial/venv.html) and install -certain libraries typeshed uses to check stub files. +### Code away! -Follow platform-specific instructions below. Following that, to automatically -check your code before committing, you can copy the file `pre-commit` to -`.git/hooks/pre-commit`. +Typeshed runs continuous integration (CI) on all pull requests. This will +automatically fix formatting (using `black`, `isort`) and run tests. +It means you can ignore all local setup on your side, focus on the +code and rely on the CI to fix everything, or point you to the places that +need fixing. + +### ... Or create a local development environment + +If you prefer to run the tests & formatting locally, it's +possible too. Follow platform-specific instructions below. + +Whichever platform you're using, you will need a +virtual environment. If you're not familiar with what it is and how it works, +please refer to this +[documentation](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/). ### Linux/Mac OS @@ -74,6 +83,19 @@ following commands from a Windows terminal: (.venv3) > python -m pip install -r requirements-tests-py3.txt ``` +## Code formatting + +The code is formatted by `black` and `isort`. + +The repository is equipped with a [`pre-commit.ci`](https://pre-commit.ci/) +configuration file. This means that you don't *need* to do anything yourself to +run the code formatters. When you push a commit, a bot will run those for you +right away and add a commit to your PR. Neat, no? + +That being said, if you *want* to run the checks locally when you commit, you +can install the hooks: please refer to the [pre-commit](https://pre-commit.com/) +documentation. + ## Where to make changes ### Standard library stubs diff --git a/pre-commit b/pre-commit deleted file mode 100755 index b3d79c25c209..000000000000 --- a/pre-commit +++ /dev/null @@ -1,28 +0,0 @@ -#!/bin/sh -# -# An example hook script that will run flake8, black, and isort -# prior to committing and will stop the commit if there are any -# warnings. Adjust BIN_DIR to the virtual environment where flake8, -# black, and isort are installed. -# -# To enable this hook, copy this file to ".git/hooks". - -BIN_DIR=./.venv3/bin - -CHANGED_FILES=$(git diff --cached --name-only --diff-filter=AM | grep .pyi || true) - -if test -n "${CHANGED_FILES}" -a -d "${BIN_DIR}"; then - ${BIN_DIR}/flake8 ${CHANGED_FILES} - ${BIN_DIR}/black --check ${CHANGED_FILES} - ${BIN_DIR}/isort --check-only ${CHANGED_FILES} - - # Replace the last two lines with the following lines - # if you want to reformat changed files automatically - # before committing. Please note that partial commits - # (git add -p) will not work and will commit the whole - # file! - # - # ${BIN_DIR}/black ${CHANGED_FILES} || true - # ${BIN_DIR}/isort -y ${CHANGED_FILES} || true - # git add ${CHANGED_FILES} -fi