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

psf · Apr 27, 2021 · 807a65f · 807a65f
1 parent 76e1602
commit 807a65f
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 2 deletions.
diff --git 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
@@ -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