Update Android binary size-related documentation.

apk_size_regressions.md: Make use of size trybot.
html_report_faq.md: Link to README.md
README.md: Add resource_sizes.py and size trybot
README.md: Document all "Overhead:" symbols.
README.md: Mention Bloaty McBloatface

Change-Id: I4cab3b7cd4c711931e9cae102e2354408cfbdd02
Reviewed-on: https://chromium-review.googlesource.com/c/1278721
Commit-Queue: agrieve <agrieve@chromium.org>
Reviewed-by: Mohamed Heikal <mheikal@chromium.org>
Reviewed-by: Eric Stevenson <estevenson@chromium.org>
Reviewed-by: Samuel Huang <huangs@chromium.org>
Reviewed-by: Peter Wen <wnwen@chromium.org>
Cr-Commit-Position: refs/heads/master@{#599719}

docs/speed/apk_size_regressions.md

@@ -19,11 +19,12 @@
 ### MonochromePublic.apk Alerts (Multiple Commits or Rolls)
 
  * Bisects [will not help you](https://bugs.chromium.org/p/chromium/issues/detail?id=678338).
- * File a bug using template in Step 2.
- * If you can afford to run a fire-and-forget command locally, use a
-   [local Android checkout](https://chromium.googlesource.com/chromium/src/+/master/docs/android_build_instructions.md)
-   along with [`//tools/binary_size/diagnose_bloat.py`](https://chromium.googlesource.com/chromium/src/+/master/tools/binary_size/README.md)
+ * For rolls, you can sometimes guess the commit(s) that caused the regression
+   by looking at the `android-binary-size` trybot result for the roll commit.
+ * Otherwise, use [diagnose_bloat.py](https://chromium.googlesource.com/chromium/src/+/master/tools/binary_size/README.md#diagnose_bloat_py)
+   in a [local Android checkout](https://chromium.googlesource.com/chromium/src/+/master/docs/android_build_instructions.md)
    to build all commits locally and find the culprit.
+ * Go to step 2.
 
 **Example:**
 
@@ -37,7 +38,7 @@
       master. In the linked example `BEFORE_GIT_REV` would actually be
       `876f37c` and not `c1dec05f`.
 
-### Monochrome.apk Alerts
+### Monochrome.apk (downstream) Alerts
 
  * The regression most likely already occurred in the upstream
    MonochromePublic.apk target. Look at the
@@ -53,7 +54,9 @@
 
 ## Step 2: File Bug or Silence Alert
 
-If the code clearly justifies the size increase, silence the alert.
+* If the commit message's `Binary-Size:` footer clearly justifies the size
+  increase, silence the alert.
+* If the regression is < 100kb and caused by an AFDO roll, silence the alert.
 
 Otherwise, file a bug (TODO: [Make this template automatic](https://github.com/catapult-project/catapult/issues/3150)):
 
@@ -66,28 +69,15 @@ Otherwise, file a bug (TODO: [Make this template automatic](https://github.com/c
 > Commit: **abc123abc123abc123abc123abc123abc123abcd**
 >
 > Link to size graph:
-> [https://chromeperf.appspot.com/report?sid=bb23072657e2d7ca892a1c3fa4643b1ee29b3a0a44d0732adda87168e89c0380&num_points=10&rev=**480214**](https://chromeperf.appspot.com/report?sid=bb23072657e2d7ca892a1c3fa4643b1ee29b3a0a44d0732adda87168e89c0380&num_points=10&rev=480214)
+> [https://chromeperf.appspot.com/report?sid=bb23072657e2d7ca892a1c3fa4643b1ee29b3a0a44d0732adda87168e89c0380&num_points=10&rev=**$CRREV**](https://chromeperf.appspot.com/report?sid=bb23072657e2d7ca892a1c3fa4643b1ee29b3a0a44d0732adda87168e89c0380&num_points=10&rev=480214)<br>
+> Link to trybot result:
+> [https://ci.chromium.org/p/chromium/builders/luci.chromium.try/android-binary-size/**$TRYJOB_NUMBER**](https://ci.chromium.org/p/chromium/builders/luci.chromium.try/android-binary-size/11111)
 >
 > Debugging size regressions is documented at:
 > https://chromium.googlesource.com/chromium/src/+/master/docs/speed/apk_size_regressions.md#Debugging-Apk-Size-Increase
 >
 > Based on the graph: **20kb of native code, 8kb of pngs.**
 >
-> _**Option 1:**_
->
-> It looks to me that the size increase is expected.<br>
-> Feel free to close as "Won't Fix" unless you can see some way to reduce size.
->
-> _**Option 2:**_
->
-> It looks like this increase was probably unexpected or might be avoidable.<br>
-> Please have a look and either:
->
-> 1. Close as "Won't Fix" with a short justification, or
-> 2. Land a revert / fix-up.
->
-> _**Option 3:**_
->
 > It's not clear to me whether or not this increase was expected.<br>
 > Please have a look and either:
 >
@@ -100,25 +90,21 @@ Otherwise, file a bug (TODO: [Make this template automatic](https://github.com/c
 > 100kb so we'd really appreciate you taking some time exploring options to
 > address this regression!
 
-*If you went with **Option 2**, and the regression is > 50kb, add
-ReleaseBlock-Stable **M-6-** (next branch cut).*
-
-Once the initial bug is filed, add a follow-up comment with the output of:
-
-``` sh
-tools/binary_size/diagnose_bloat.py GIT_REV --cloud
-```
+If the regression is >50kb, add ReleaseBlock-Stable **M-##** (next branch cut).*
 
 # Debugging Apk Size Increase
 
 ## Step 1: Identify what Grew
 
 Figure out which file within the `.apk` increased (native library, dex, pak
-resources, etc) by looking at the breakdown in the size graphs linked to in the
-bug (if it was not linked in the bug, see above).
+resources, etc.) by looking at the trybot results or size graphs that were
+linked from the bug (if it was not linked in the bug, see above).
 
 **See [//docs/speed/binary_size/metrics.md](https://chromium.googlesource.com/chromium/src/+/master/docs/speed/binary_size/metrics.md)
-for a description of the metrics we track.**
+for a description of high-level binary size metrics.**
+
+**See [//tools/binary_size/README.md](https://chromium.googlesource.com/chromium/src/+/master/tools/binary_size/README.md)
+for a description of binary size tools.**
 
 ## Step 2: Analyze
 
@@ -130,8 +116,8 @@ for a description of the metrics we track.**
 ### Growth is from Native Resources (pak files)
 
  * Ensure `compress="gzip"` is used for all `chrome:` pages.
- * Use [//tools/binary_size/diagnose_bloat.py](https://chromium.googlesource.com/chromium/src/+/master/tools/binary_size/README.md)
-   to show a diff of pak entries.
+ * Look at the SuperSize reports from the trybot to look for unexpected
+   resources, or unreasonably large symbols.
 
 ### Growth is from Images
 
@@ -143,20 +129,19 @@ for a description of the metrics we track.**
 
 ### Growth is from Native Code
 
- * Use [//tools/binary_size/diagnose_bloat.py](https://chromium.googlesource.com/chromium/src/+/master/tools/binary_size/README.md)
-to show a diff of ELF symbols.
-   * Googlers should use the speedy `--cloud` option. E.g.:
-   * `tools/binary_size/diagnose_bloat.py 0f30c9488bd2bdc1db2749cd4683994a764a44c9 --cloud`
- * Paste the diff into the bug.
+ * Look at the SuperSize reports from the trybot to look for unexpected symbols,
+   or unreasonably large symbols.
  * If the diff looks reasonable, close as `Won't Fix`.
  * Otherwise, try to refactor a bit (e.g.
  [move code out of templates](https://bugs.chromium.org/p/chromium/issues/detail?id=716393)).
- * If symbols are larger than expected, use the `Disassemble()` feature of `supersize console` to see what is going on.
+   * Use [//tools/binary_size/diagnose_bloat.py](https://chromium.googlesource.com/chromium/src/+/master/tools/binary_size/README.md)
+     or the android-binary-size trybot to spot-check your local changes.
+ * If symbols are larger than expected, use the `Disassemble()` feature of
+   `supersize console` to see what is going on.
 
 ### Growth is from Java Code
 
- * Use [//tools/binary_size/diagnose_bloat.py](https://chromium.googlesource.com/chromium/src/+/master/tools/binary_size/README.md)
-   to show a diff of Java symbols.
+ * Look at the SuperSize reports from the trybot to look for unexpected methods.
  * Ensure any new Java deps are as specific as possible.
  * If the change doesn't look suspect, check to see if the regression still
    exists when internal proguard is used (see
@@ -166,9 +151,8 @@ to show a diff of ELF symbols.
 
 ### Growth is from "other lib size" or "Unknown files size"
 
- * File a bug against agrieve@ to fix
-   [resource_sizes.py](https://cs.chromium.org/chromium/src/build/android/resource_sizes.py).
- * ...or fix it yourself. This script will output the list of unknown filenames.
+ * File a bug under [Tools > BinarySize](https://bugs.chromium.org/p/chromium/issues/list?q=component%3ATools%3EBinarySize)
+   with a link to your commit.
 
 ### You Would Like Assistance
 
@@ -176,23 +160,25 @@ to show a diff of ELF symbols.
 
 # For Binary Size Sheriffs
 
-## Step 1: Check work queue daily
+## Step 1: Check Work Queue Daily
 
- * Bugs requiring sheriffs to take a look at are labeled `Performance-Sheriff` and `Performance-Size` [here](https://bugs.chromium.org/p/chromium/issues/list?q=label:Performance-Sheriff%20label:Performance-Size&sort=-modified).
- * After resolving the bug by finding an owner or debugging or commenting, remove the `Performance-Sheriff` label.
+ * Bugs requiring sheriffs to take a look at are labeled `Performance-Sheriff`
+   and `Performance-Size` [here](https://bugs.chromium.org/p/chromium/issues/list?q=label:Performance-Sheriff%20label:Performance-Size&sort=-modified).
+ * After resolving the bug by finding an owner or debugging or commenting,
+   remove the `Performance-Sheriff` label.
 
-## Step 2: Check alerts regularly
+## Step 2: Check Alerts Regularly
 
  * **IMPORTANT: Check the [perf bot page](https://ci.chromium.org/buildbot/chromium.perf/Android%20Builder%20Perf/)
  several times a day to make sure it isn't broken (and ping/file a bug if it is).**
    * At the very least you need to check this once in the morning and once in
    the afternoon.
    * If you don't and the builder is broken either you or the next sheriff will
-   have to manually build and diff the broken range (via. diagnose_bloat.py) to
-   see if we missed any regressions.
+   have to manually build and diff the broken range (via. `diagnose_bloat.py`)
+   to see if we missed any regressions.
    * This is necessary even if the next passing build doesn't create an alert
    because the range could contain a large regression with multiple offsetting
    decreases.
  * Check [alert page](https://chromeperf.appspot.com/alerts?sheriff=Binary%20Size%20Sheriff) regularly for new alerts.
- * Join [binary-size-alerts@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/binary-size-alerts). Eventually it will be all set up.
- * Deal with alerts as outlined above.
+ * Join [g/chrome-binary-size-alerts](https://goto.google.com/chrome-binary-size-alerts).
+ * Deal with alerts as outlined above.
\ No newline at end of file

tools/binary_size/html_report_faq.md

@@ -50,9 +50,9 @@ _*_ | Expand all sibling containers of the current node.
 
 ## Symbols
 
-### What are "Other entries"?
-The symbol type "Other entries" refers to symbols that don't fall in one of the
-defined symbol categories. This includes images and `.bin` files.
+A description of how size information is collected, including descriptions of
+each symbol type, is detailed in
+[README.md](README.md#how-are-symbols-collected).
 
 ### What are "Other small" symbols for?
 To reduce the size of the generated data file, small symbols are omitted by