]> git.madduck.net Git - etc/vim.git/blob - docs/the_black_code_style/index.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Doc: Developer reference update (#3755)
[etc/vim.git] / docs / the_black_code_style / index.md
1 # The Black Code Style
2
3 ```{toctree}
4 ---
5 hidden:
6 ---
7
8 Current style <current_style>
9 Future style <future_style>
10 ```
11
12 _Black_ is a PEP 8 compliant opinionated formatter with its own style.
13
14 While keeping the style unchanged throughout releases has always been a goal, the
15 _Black_ code style isn't set in stone. It evolves to accommodate for new features in the
16 Python language and, occasionally, in response to user feedback. Large-scale style
17 preferences presented in {doc}`current_style` are very unlikely to change, but minor
18 style aspects and details might change according to the stability policy presented
19 below. Ongoing style considerations are tracked on GitHub with the
20 [style](https://github.com/psf/black/labels/T%3A%20style) issue label.
21
22 (labels/stability-policy)=
23
24 ## Stability Policy
25
26 The following policy applies for the _Black_ code style, in non pre-release versions of
27 _Black_:
28
29 - If code has been formatted with _Black_, it will remain unchanged when formatted with
30   the same options using any other release in the same calendar year.
31
32   This means projects can safely use `black ~= 22.0` without worrying about formatting
33   changes disrupting their project in 2022. We may still fix bugs where _Black_ crashes
34   on some code, and make other improvements that do not affect formatting.
35
36   In rare cases, we may make changes affecting code that has not been previously
37   formatted with _Black_. For example, we have had bugs where we accidentally removed
38   some comments. Such bugs can be fixed without breaking the stability policy.
39
40 - The first release in a new calendar year _may_ contain formatting changes, although
41   these will be minimised as much as possible. This is to allow for improved formatting
42   enabled by newer Python language syntax as well as due to improvements in the
43   formatting logic.
44
45 - The `--preview` flag is exempt from this policy. There are no guarantees around the
46   stability of the output with that flag passed into _Black_. This flag is intended for
47   allowing experimentation with the proposed changes to the _Black_ code style.
48
49 Documentation for both the current and future styles can be found:
50
51 - {doc}`current_style`
52 - {doc}`future_style`