From c75abed63ef284d7de54db87777951d6c668eefc Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Thu, 21 Oct 2021 08:02:38 -0700 Subject: [PATCH] Define a stability policy (#2529) MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 Co-authored-by: Łukasz Langa --- CHANGES.md | 1 + docs/faq.md | 12 +++++++++--- docs/the_black_code_style/index.rst | 30 ++++++++++++++++++++++++++--- 3 files changed, 37 insertions(+), 6 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 864f0a5..2a3a60f 100644 --- a/CHANGES.md +++ b/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) diff --git a/docs/faq.md b/docs/faq.md index c361add..9fe5392 100644 --- a/docs/faq.md +++ b/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 -likely it is bound to happen. Sometime. Eventually. In terms of running _Black_ though, -Python 3.6 or newer is required. +to format Python 2 files too! In terms of running _Black_ though, 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? 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: -- 2.39.5