[clang] 63f927b - Update release notes with porting guide for AST Matchers

[Stephen Kelly via cfe-commits]

Author: Stephen Kelly
Date: 2020-05-27T13:21:06+01:00
New Revision: 63f927b17a1ce18cb922c441ffc0691a71d550b8

URL: https://github.com/llvm/llvm-project/commit/63f927b17a1ce18cb922c441ffc0691a71d550b8
DIFF: https://github.com/llvm/llvm-project/commit/63f927b17a1ce18cb922c441ffc0691a71d550b8.diff

LOG: Update release notes with porting guide for AST Matchers

Added: 
    

Modified: 
    clang/docs/ReleaseNotes.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 571b54904754..8f9dc81ec0b3 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -259,6 +259,36 @@ AST Matchers
   uses ``IgnoreUnlessSpelledInSource`` by default.  The mode can be changed
   using ``set traversal AsIs`` in the ``clang-query`` environment.
 
+  As this change requires downstream tools which use AST Matchers to adapt
+  to the new default, a porting guide may be useful for downstream tools
+  needing to adapt.
+
+  Note that although there are many steps below, only the first is
+  non-optional. The steps are intentionally extemely granular to facilitate
+  understanding of the guide itself. It is reasonable to do some of the
+  steps at the same time if you understand the guide:
+
+  1. Use ``(your ASTContext instance).getParentMapContext().setTraversalKind(TK_AsIs)``
+     to restore the previous behavior for your tool.  All further steps in
+     this porting guide are optional.
+  2. Wrap your existing matcher expressions with ``traverse(TK_AsIs, ...)``
+     before passing them to ``ASTMatchFinder::addMatcher``.
+  3. Remove ``(your ASTContext instance).getParentMapContext().setTraversalKind(TK_AsIs)``
+     from your tool so that the default behavior of your tool matches the
+     default behavior of upstream clang. This is made possible by wrapping
+     your matchers in ``traverse(TK_AsIs, ...)`` from step (2).
+  4. Audit your matcher expressions and remove ``traverse(TK_AsIs, ...)``
+     where not needed.
+  5. Audit your matcher expressions and remove calls to ``ignoring*()``
+     matchers where not needed.
+  6. Audit your matcher expressions and consider whether the matcher is
+     better using the ``TK_AsIs`` mode or if it can be better expressed in
+     the default mode. For example, some matchers explicitly match
+     ``has(implicitCastExpr(has(...)))``. Such matchers are sometimes
+     written by author who were unaware of the existence of the
+     ``ignoring*()`` matchers.
+
+
 clang-format
 ------------