Apply suggestions from Pradyun's review

Co-authored-by: Pradyun Gedam <pradyunsg@gmail.com>

CHANGES.md

@@ -4,8 +4,7 @@
 
 ### _Black_
 
-- Announce upcoming new stability policy and intent drop the beta marker and Python 2
-  support (#2529)
+- 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,9 +31,9 @@ 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 from 2022, we will provide a formal stability guarantee: for all releases in
-the same year, we will produce the same formatting output. Users can opt in to breaking
-changes with the `--future` flag.
+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?
 
@@ -78,7 +78,7 @@ For formatting, yes! [Install](getting_started.md#installation) with the `python
 to format Python 2 files too! In terms of running _Black_ though, Python 3.6 or newer is
 required.
 
-We will drop support for Python 2 in the first stable release, expected for
+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,27 +9,33 @@ The Black Code Style
 
 *Black* is a PEP 8 compliant opinionated formatter with its own style.
 
-While keeping the style unchanged throughout releases has always been a
-goal, the *Black* code style has never been 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.
 
-Starting from January 2022, we will follow a more formal stability policy:
+Stability Policy
+----------------
 
-- *Black* guarantees that 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
+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.
-- We will have an ``--future`` flag that may produce different
-  formatting output. We make no guarantee about the stability of this flag
-  between releases. At the end of the year, we will evaluate anything we
-  put under the ``--future`` flag and if we are happy with it, the
-  style change will be promoted to the stable style for the next year.
-
-At the same time, we will finally drop the beta marker from our releases,
-and we will drop support for Python 2.
-The first release to follow the new policy will be 22.0.0.
+
+- 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: