Stability policy: permit exceptional changes for unformatted code (#3155)

diff --git a/CHANGES.md b/CHANGES.md
index 1d30045f48b1efc0278b92c11d3337ffa89c7ce4..0bfa7ccd62cfc1d46826e9124495d7c658997b8a 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -27,6 +27,9 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+- 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
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->

diff --git a/docs/the_black_code_style/index.md b/docs/the_black_code_style/index.md
index d1508552fee8311be2fc77776dd96fda71cfdaa3..c7f29af6c736125e41d218b8b9ee22deac5b10b4 100644 (file)
--- 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