Bump actions/checkout from 3 to 4 (#3883)

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

diff --git a/docs/contributing/the_basics.md b/docs/contributing/the_basics.md
index d9df0ea30c4702e2ed6b6f80524d5551c0ccd75a..40d233257e30a5ed1c1ee56f73c6f876d063d274 100644 (file)
--- a/docs/contributing/the_basics.md
+++ b/docs/contributing/the_basics.md
@@ -4,14 +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 all development dependencies using:
+Install development dependencies inside a virtual environment of your choice, for
+example:

 
 ```console
 $ python3 -m venv .venv
 
 ```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


@@ -30,8 +33,8 @@ 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

 ```
 
 ### News / Changelog Requirement
 ```
 
 ### News / Changelog Requirement


@@ -54,7 +57,9 @@ go back and workout what to add to the `CHANGES.md` for each release.
 
 If a change would affect the advertised code style, please modify the documentation (The
 _Black_ code style) to reflect that change. Patches that fix unintended bugs in
 
 If a change would affect the advertised code style, please modify the documentation (The
 _Black_ code style) to reflect that change. Patches that fix unintended bugs in

-formatting don't need to be mentioned separately though.
+formatting don't need to be mentioned separately though. If the change is implemented
+with the `--preview` flag, please include the change in the future style document
+instead and write the changelog entry under a dedicated "Preview changes" heading.

 
 ### Docs Testing
 
 
 ### Docs Testing
 


@@ -62,22 +67,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,