diff --git a/CHANGES.md b/CHANGES.md index 6888e32ae4b..2a3a60f82c6 100644 --- a/CHANGES.md +++ b/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) diff --git a/docs/faq.md b/docs/faq.md index e11477e33ab..692283700f6 100644 --- a/docs/faq.md +++ b/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? diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst index f9047d7aa66..7c2e1753937 100644 --- a/docs/the_black_code_style/index.rst +++ b/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: