Define a stability policy (#2529)

Fixes #2394. Eventually fixes #517.

This is essentially @pradyunsg's suggestion from #2394. I suggest that at the
same time we start the formal stability policy, we take a few other disruptive steps
and drop Python 2 and the "b" marker.

Co-authored-by: Pradyun Gedam <pradyunsg@gmail.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>

CHANGES.md

@@ -4,6 +4,7 @@
 
 ### _Black_
 
+- Document stability policy, that will apply for non-beta releases (#2529)
 - Add new `--workers` parameter (#2514)
 - Fixed feature detection for positional-only arguments in lambdas (#2532)
 - Bumped typed-ast version minimum to 1.4.3 for 3.10 compatiblity (#2519)

docs/faq.md

@@ -31,6 +31,10 @@ pragmatism. However, _Black_ is still in beta so style changes are both planned
 still proposed on the issue tracker. See
 [The Black Code Style](the_black_code_style/index.rst) for more details.
 
+Starting in 2022, the formatting output will be stable for the releases made in the same
+year (other than unintentional bugs). It is possible to opt-in to the latest formatting
+styles, using the `--future` flag.
+
 ## Why is my file not formatted?
 
 Most likely because it is ignored in `.gitignore` or excluded with configuration. See
@@ -71,9 +75,11 @@ disabled-by-default counterpart W504. E203 should be disabled while changes are
 ## Does Black support Python 2?
 
 For formatting, yes! [Install](getting_started.md#installation) with the `python2` extra
-to format Python 2 files too! There are no current plans to drop support, but most
+to format Python 2 files too! In terms of running _Black_ though, Python 3.6 or newer is
-likely it is bound to happen. Sometime. Eventually. In terms of running _Black_ though,
+required.
-Python 3.6 or newer is required.
+
+Note that this support will be dropped in the first stable release, expected for
+January 2022. See [The Black Code Style](the_black_code_style/index.rst) for details.
 
 ## Why does my linter or typechecker complain after I format my code?
 

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
+While keeping the style unchanged throughout releases has always been a goal,
-goal, the *Black* code style isn't set in stone. Sometimes it's modified in response to
+the *Black* code style isn't set in stone. It evolves to accomodate for new features
-user feedback or even changes to the Python language!
+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: