diff --git a/CHANGES.md b/CHANGES.md index 1d30045f48b..0bfa7ccd62c 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -27,6 +27,9 @@ +- Reword the stability policy to say that we may, in rare cases, make changes that + affect code that was not previously formatted by _Black_ (#3155) + ### Integrations diff --git a/docs/the_black_code_style/index.md b/docs/the_black_code_style/index.md index d1508552fee..c7f29af6c73 100644 --- a/docs/the_black_code_style/index.md +++ b/docs/the_black_code_style/index.md @@ -24,13 +24,16 @@ below. Ongoing style considerations are tracked on GitHub with the 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. +- If code has been formatted with _Black_, it will remain unchanged when formatted with + the same options using any other release in the same 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. + This means projects can safely use `black ~= 22.0` without worrying about 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. + + In rare cases, we may make changes affecting code that has not been previously + formatted with _Black_. For example, we have had bugs where we accidentally removed + some comments. Such bugs can be fixed without breaking the stability policy. - 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