README: fix "Pragmatism" link target (#2901)

[etc/vim.git] / docs / the_black_code_style / index.rst

diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst
index 4693437be8bb31c26cb791ded702d18ce860ac97..511a6ecf0998cc2427d88f57afdfcf3f5d69da88 100644 (file)
--- a/docs/the_black_code_style/index.rst
+++ b/docs/the_black_code_style/index.rst
@@ -9,9 +9,37 @@ The Black Code Style
 
 *Black* is a PEP 8 compliant opinionated formatter with its own style.
 
 
 *Black* is a PEP 8 compliant opinionated formatter with its own style.
 

-It should be noted that while keeping the style unchanged throughout releases is a
-goal, the *Black* code style isn't set in stone. Sometimes it's modified in response to
-user feedback or even changes to the Python language!
+While keeping the style unchanged throughout releases has always been a goal,
+the *Black* code style isn't set in stone. It evolves to accommodate for new features
+in the Python language and, occasionally, in response to user feedback.
+Large-scale style preferences presented in :doc:`current_style` are very unlikely to
+change, but minor style aspects and details might change according to the stability
+policy presented below. Ongoing style considerations are tracked on GitHub with the
+`design <https://github.com/psf/black/labels/T%3A%20design>`_ issue label.
+
+Stability Policy
+----------------
+
+The following policy applies for the *Black* code style, in non pre-release
+versions of *Black*:
+
+- The same code, formatted with the same options, will produce the same
+  output for all releases in a given calendar year.
+
+  This means projects can safely use `black ~= 22.0` without worrying about
+  major formatting changes disrupting their project in 2022. We may still
+  fix bugs where *Black* crashes on some code, and make other improvements
+  that do not affect formatting.
+
+- The first release in a new calendar year *may* contain formatting changes,
+  although these will be minimised as much as possible. This is to allow for
+  improved formatting enabled by newer Python language syntax as well as due
+  to improvements in the formatting logic.
+
+- The ``--preview`` flag is exempt from this policy. There are no guarantees
+  around the stability of the output with that flag passed into *Black*. This
+  flag is intended for allowing experimentation with the proposed changes to
+  the *Black* code style.

 
 Documentation for both the current and future styles can be found:
 
 
 Documentation for both the current and future styles can be found: