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 864894b491fbe3cdaca802911d952cc2a5530c17..bc1680eecfd835e92fbffa3fd99cac39c9856ed0 100644 (file)
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -58,7 +58,26 @@ Further examples of invoking the tests
 (.venv)$ tox -e py -- --print-tree-diff=False
 ```
 
-`Black` has two pytest command-line options affecting test files in `tests/data/` that
+### 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`.