From 807a65f9d59d97a606575dc69110d7a5dfd98641 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Tue, 27 Apr 2021 14:00:17 -0700
Subject: [PATCH] Update discussion of AST safety check in README (#2159)

---
 CHANGES.md | 5 +++++
 README.md  | 6 ++++--
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 37b5da6..a30668d 100644
--- 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 8d6adb0..c7577fb 100644
--- 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
 
-- 
2.39.5