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

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:

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