X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/62bfbd6a63dcac2f6f31eb014f69397c9eb967d2..62ed5389fca51384721245ff1c2f1c62a13a04ff:/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..7c2e175 100644
--- a/docs/the_black_code_style/index.rst
+++ b/docs/the_black_code_style/index.rst
@@ -9,9 +9,33 @@ 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 accomodate for new features
+in the Python language and, ocassionally, in response to user feedback.
+
+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 ``--future`` flag is exempt from this policy. There are no guarentees
+  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: