X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/62bfbd6a63dcac2f6f31eb014f69397c9eb967d2..5379d4f3f460ec9b7063dd1cc10f437b0edf9ae3:/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 4693437..511a6ec 100644
--- 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.
 
-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: