From d2c938eb02c414057aa2186c7ae695d5d0d14377 Mon Sep 17 00:00:00 2001 From: Cooper Lees Date: Sun, 23 Jan 2022 12:34:01 -0800 Subject: [PATCH 1/1] Remove Beta mentions in README + Docs (#2801) - State we're now stable and that we'll uphold our formatting changes as per policy - Link to The Black Style doc. Co-authored-by: Jelle Zijlstra --- README.md | 15 ++++++--------- docs/faq.md | 11 ++++------- docs/index.rst | 14 ++++++-------- 3 files changed, 16 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index daeb747..e900d2d 100644 --- a/README.md +++ b/README.md @@ -64,16 +64,13 @@ Further information can be found in our docs: - [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html) -### NOTE: This is a beta product - _Black_ is already [successfully used](https://github.com/psf/black#used-by) by many -projects, small and big. Black has a comprehensive test suite, with efficient parallel -tests, and our own auto formatting and parallel Continuous Integration runner. However, -_Black_ is still beta. Things will probably be wonky for a while. This is made explicit -by the "Beta" trove classifier, as well as by the "b" in the version number. What this -means for you is that **until the formatter becomes stable, you should expect some -formatting to change in the future**. That being said, no drastic stylistic changes are -planned, mostly responses to bug reports. +projects, small and big. _Black_ has a comprehensive test suite, with efficient parallel +tests, and our own auto formatting and parallel Continuous Integration runner. Now that +we have become stable, you should not expect large formatting to changes in the future. +Stylistic changes will mostly be responses to bug reports and support for new Python +syntax. For more information please refer to the +[The Black Code Style](docs/the_black_code_style/index.rst). Also, as a safety measure which slows down processing, _Black_ will check that the reformatted code still produces a valid AST that is effectively equivalent to the diff --git a/docs/faq.md b/docs/faq.md index 1ebdcd9..0cff6ae 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -17,9 +17,8 @@ though. ## Is Black safe to use? -Yes, for the most part. _Black_ is strictly about formatting, nothing else. But because -_Black_ is still in [beta](index.rst), some edges are still a bit rough. To combat -issues, the equivalence of code after formatting is +Yes. _Black_ is strictly about formatting, nothing else. Black strives to ensure that +after formatting the AST is [checked](the_black_code_style/current_style.md#ast-before-and-after-formatting) with limited special cases where the code is allowed to differ. If issues are found, an error is raised and the file is left untouched. Magical comments that influence linters and @@ -27,10 +26,8 @@ other tools, such as `# noqa`, may be moved by _Black_. See below for more detai ## How stable is Black's style? -Quite stable. _Black_ aims to enforce one style and one style only, with some room for -pragmatism. However, _Black_ is still in beta so style changes are both planned and -still proposed on the issue tracker. See -[The Black Code Style](the_black_code_style/index.rst) for more details. +Stable. _Black_ aims to enforce one style and one style only, with some room for +pragmatism. 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 diff --git a/docs/index.rst b/docs/index.rst index 6818c03..8a8da0d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,16 +18,14 @@ can focus on the content instead. Try it out now using the `Black Playground `_. -.. admonition:: Note - this is a beta product +.. admonition:: Note - Black is now stable! - *Black* is already `successfully used `_ by + *Black* is `successfully used `_ by many projects, small and big. *Black* has a comprehensive test suite, with efficient - parallel tests, our own auto formatting and parallel Continuous Integration runner. - However, *Black* is still beta. Things will probably be wonky for a while. This is - made explicit by the "Beta" trove classifier, as well as by the "b" in the version - number. What this means for you is that **until the formatter becomes stable, you - should expect some formatting to change in the future**. That being said, no drastic - stylistic changes are planned, mostly responses to bug reports. + parallel tests, our own auto formatting and parallel Continuous Integration runner. + Now that we have become stable, you should not expect large formatting to changes in + the future. Stylistic changes will mostly be responses to bug reports and support for new Python + syntax. Also, as a safety measure which slows down processing, *Black* will check that the reformatted code still produces a valid AST that is effectively equivalent to the -- 2.39.5