Fix cache versioning when BLACK_CACHE_DIR is set (#3937)

[etc/vim.git] / docs / contributing / the_basics.md

diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index 23fbb8a3d7e1d939a2286caf5b4a095ac900168b..bc1680eecfd835e92fbffa3fd99cac39c9856ed0 100644 (file)
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -4,15 +4,17 @@ An overview on contributing to the _Black_ project.
 
 ## Technicalities
 
 
 ## Technicalities
 

-Development on the latest version of Python is preferred. As of this writing it's 3.9.
-You can use any operating system.
+Development on the latest version of Python is preferred. You can use any operating
+system.

 
 Install development dependencies inside a virtual environment of your choice, for
 example:
 
 ```console
 $ python3 -m venv .venv
 
 Install development dependencies inside a virtual environment of your choice, for
 example:
 
 ```console
 $ python3 -m venv .venv

-$ source .venv/bin/activate
+$ source .venv/bin/activate # activation for linux and mac
+$ .venv\Scripts\activate # activation for windows
+

 (.venv)$ pip install -r test_requirements.txt
 (.venv)$ pip install -e .[d]
 (.venv)$ pre-commit install
 (.venv)$ pip install -r test_requirements.txt
 (.venv)$ pip install -e .[d]
 (.venv)$ pre-commit install


@@ -31,10 +33,67 @@ the root of the black repo:
 # Optional Fuzz testing
 (.venv)$ tox -e fuzz
 
 # Optional Fuzz testing
 (.venv)$ tox -e fuzz
 

-# Optional CI run to test your changes on many popular python projects
-(.venv)$ black-primer [-k -w /tmp/black_test_repos]
+# Format Black itself
+(.venv)$ tox -e run_self

 ```
 
 ```
 

+### Development
+
+Further examples of invoking the tests
+
+```console
+# Run all of the above mentioned, in parallel
+(.venv)$ tox --parallel=auto
+
+# Run tests on a specific python version
+(.venv)$ tox -e py39
+
+# pass arguments to pytest
+(.venv)$ tox -e py -- --no-cov
+
+# print full tree diff, see documentation below
+(.venv)$ tox -e py -- --print-full-tree
+
+# disable diff printing, see documentation below
+(.venv)$ tox -e py -- --print-tree-diff=False
+```
+
+### Testing
+
+All aspects of the _Black_ style should be tested. Normally, tests should be created as
+files in the `tests/data/cases` directory. These files consist of up to three parts:
+
+- A line that starts with `# flags: ` followed by a set of command-line options. For
+  example, if the line is `# flags: --preview --skip-magic-trailing-comma`, the test
+  case will be run with preview mode on and the magic trailing comma off. The options
+  accepted are mostly a subset of those of _Black_ itself, except for the
+  `--minimum-version=` flag, which should be used when testing a grammar feature that
+  works only in newer versions of Python. This flag ensures that we don't try to
+  validate the AST on older versions and tests that we autodetect the Python version
+  correctly when the feature is used. For the exact flags accepted, see the function
+  `get_flags_parser` in `tests/util.py`. If this line is omitted, the default options
+  are used.
+- A block of Python code used as input for the formatter.
+- The line `# output`, followed by the output of _Black_ when run on the previous block.
+  If this is omitted, the test asserts that _Black_ will leave the input code unchanged.
+
+_Black_ has two pytest command-line options affecting test files in `tests/data/` that
+are split into an input part, and an output part, separated by a line with`# output`.
+These can be passed to `pytest` through `tox`, or directly into pytest if not using
+`tox`.
+
+#### `--print-full-tree`
+
+Upon a failing test, print the full concrete syntax tree (CST) as it is after processing
+the input ("actual"), and the tree that's yielded after parsing the output ("expected").
+Note that a test can fail with different output with the same CST. This used to be the
+default, but now defaults to `False`.
+
+#### `--print-tree-diff`
+
+Upon a failing test, print the diff of the trees as described above. This is the
+default. To turn it off pass `--print-tree-diff=False`.
+

 ### News / Changelog Requirement
 
 `Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
 ### News / Changelog Requirement
 
 `Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If


@@ -65,22 +124,10 @@ If you make changes to docs, you can test they still build locally too.
 
 ```console
 (.venv)$ pip install -r docs/requirements.txt
 
 ```console
 (.venv)$ pip install -r docs/requirements.txt

-(.venv)$ pip install [-e] .[d]
+(.venv)$ pip install -e .[d]

 (.venv)$ sphinx-build -a -b html -W docs/ docs/_build/
 ```
 
 (.venv)$ sphinx-build -a -b html -W docs/ docs/_build/
 ```
 

-## black-primer
-
-`black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
-if we get source code changes. It will error on formatting changes or errors. Please run
-before pushing your PR to see if you get the actions you would expect from _Black_ with
-your PR. You may need to change
-[primer.json](https://github.com/psf/black/blob/main/src/black_primer/primer.json)
-configuration for it to pass.
-
-For more `black-primer` information visit the
-[documentation](./gauging_changes.md#black-primer).
-

 ## Hygiene
 
 If you're fixing a bug, add a test. Run it first to confirm it fails, then fix the bug,
 ## Hygiene
 
 If you're fixing a bug, add a test. Run it first to confirm it fails, then fix the bug,