Add information on mapping information changes.
Bug: b/279555726
Fixes: b/214018111
Fixes: b/279555568
RELNOTES: R8 now encodes source-file mapping information for all
builds (effectively assuming -keepattributes SourceFile). When targeting
min-api 26 and above (and discarding source file or renaming it to
nothing or "SourceFile"), R8 will also encode all lines in the mapping
information (effectively assuming -keepattributes LineNumberTable, for
such builds).
Change-Id: I05d2312be7cfd6a282862f0420a5522cf874102d
diff --git a/compatibility-faq.md b/compatibility-faq.md
index 5614f6f..f0d9c05 100644
--- a/compatibility-faq.md
+++ b/compatibility-faq.md
@@ -30,6 +30,20 @@
Additionally, for attributes describing a relationship such as `InnerClass` and
`EnclosingMethod`, non-compat mode requires both endpoints being kept.
+## Stack traces and retracing
+When compiling with R8, a mapping file can be produced to support mapping stack
+traces of the R8 optimized program back to the original source information.
+
+Starting with R8 version 8.2, the compiler will retain full original source file
+names in the mapping information without the need to specify
+`-keepattributes SourceFile`.
+
+In addition, builds that target API level 26 or above (and don't specify custom
+source-file information) will also retain mapping information for all lines
+without the need to specify `-keepattributes LineNumberTable`.
+
+More information on R8 mapping files can be found in the [retrace doc](doc/retrace.md).
+
# Troubleshooting
The rest of this document describes known issues with libraries that use
