Update discussion of AST safety check in README (#2159)

diff --git a/CHANGES.md b/CHANGES.md
index 37b5da6a40dfb29e0235956b65bd37bd597ac4c3..a30668d33b22399c9a1bc4d60ede7f3276916ec8 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -2,6 +2,11 @@
 
 ### Unreleased
 
+#### _Black_
+
+- Clarify that _Black_ may change the AST, especially when cleaning up docstrings.
+  (#2159)
+
 #### _Packaging_
 
 - Install `primer.json` (used by `black-primer` by default) with black. (#2154)

diff --git a/README.md b/README.md
index 8d6adb0567ef487611c6cb91ab4269d96c64932b..c7577fbbd041eaf2a8d4c1230ffaf9b74c7f62d7 100644 (file)
--- a/README.md
+++ b/README.md
@@ -238,8 +238,10 @@ change in the future**. That being said, no drastic stylistic changes are planne
 mostly responses to bug reports.
 
 Also, as a temporary safety measure, _Black_ will check that the reformatted code still
-produces a valid AST that is equivalent to the original. This slows it down. If you're
-feeling confident, use `--fast`.
+produces a valid AST that is mostly equivalent to the original. This slows it down. If
+you're feeling confident, use `--fast`. In a few contexts, Black does make changes to
+the AST: it cleans up whitespace in docstrings, adds or removes parentheses in some
+`del` statements, and may move around type comments.
 
 ## The _Black_ code style