BASELINE: Update Chromium to 84.0.4147.141

Change-Id: Ib85eb4cfa1cbe2b2b81e5022c8cad5c493969535
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>

79 files changed, 3832 insertions, 284 deletions

diff --git a/chromium/docs/README.md b/chromium/docs/README.md
index 8fef521773f..2c89081b5da 100644
--- a/chromium/docs/README.md
+++ b/chromium/docs/README.md
@@ -286,6 +286,8 @@ used when committed.
 *   [User Agent in Chrome for iOS](ios/user_agent.md) - Notes on User Agent
     strings using Chrome for iOS.
 *   [Running iOS test suites locally](ios/testing.md)
+*   [Working With Project Files in iOS](ios/working_with_files.md) - How
+    to add, remove, and rename files in the iOS Chromium project.
 
 ### Misc Chrome-OS-Specific Docs
 *   [Setting up captive portals and other restrictive networks](login/restrictive_networks.md)
@@ -377,6 +379,10 @@ used when committed.
 *   [Mojo “Style” Guide](security/mojo.md) - Recommendations for best practices
     from Mojo and IPC reviewers
 
+### Speed
+*   [Chrome Speed](speed/README.md) - Documentation for performance measurements and regressions in Chrome.
+*   [Chrome Speed Metrics](speed_metrics/README.md) - Documentation about user experience metrics in the web and their JavaScript APIs.
+
 ### WebXR
 *   [Running OpenVR Without Headset](xr/run_openvr_without_headset.md) -
     Instructions for running OpenVR on Windows without a headset
diff --git a/chromium/docs/accessibility.md b/chromium/docs/accessibility.md
index 03e84e8e4ce..8f6a99b8a55 100644
--- a/chromium/docs/accessibility.md
+++ b/chromium/docs/accessibility.md
@@ -8,6 +8,7 @@
 * [Offscreen, Invisible and Size](accessibility/offscreen.md)
 * [Text to Speech in Chrome and Chrome OS](accessibility/tts.md)
 * [Performance Measurement](accessibility/perf.md)
+* [Reader Mode on Desktop Platforms](accessibility/reader_mode.md)
 
 ## Chrome OS
 
diff --git a/chromium/docs/accessibility/autoclick.md b/chromium/docs/accessibility/autoclick.md
index 298d5b3ba19..dd088bb88ec 100644
--- a/chromium/docs/accessibility/autoclick.md
+++ b/chromium/docs/accessibility/autoclick.md
@@ -30,7 +30,7 @@ the label “autoclick” (or, use
 [this template](https://bugs.chromium.org/p/chromium/issues/entry?summary=Autoclick%20-%20&status=Available&cc=katie%40chromium.org%2C%20qqwangxin%40google.com&labels=Pri-3%2C%20autoclick%2C&components=UI>Accessibility)).
 
 
-Open bugs have the label 
+Open bugs have the label
 “[autoclick](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=label%3Aautoclick)”.
 
 ## Developing
@@ -138,7 +138,7 @@ to accessibility tree information, and using a HitTest is able to find the view
 at the scroll location, then walks up the tree to find the first view which can
 scroll, or stops at the nearest window or dialog bounds. This logic takes place
 in autoclick.js, onAutomationHitTestResult_. When the scrolling location is
-found, the bounds of the scrollable area are highlighted with a focus ring. 
+found, the bounds of the scrollable area are highlighted with a focus ring.
 In addition, the bounds are sent back through the AccessibilityPrivate API,
 routed to the AutoclickController, which passes it via the
 AutoclickMenuBubbleController to the AutoclickScrollBubbleController, which
@@ -165,9 +165,9 @@ draw the custom shape buttons for left/right/up/down scrolling.
 The autoclick bubble menu can be positioned in the four corners of the screen
 and defaults to the same location as the volume widget (which depends on
 LTR/RTL language). AutoclickMenuBubbleController takes a preferred
-AutoclickMenuPosition enum and uses that to determine the best position for
+FloatingMenuPosition enum and uses that to determine the best position for
 the menu in AutoclickMenuBubbleController::SetPosition. This function finds
-the ideal corner of the screen, then uses CollisionDetectionUtils (also used 
+the ideal corner of the screen, then uses CollisionDetectionUtils (also used
 by Picture-in-Picture) to refine the position to avoid collisions with system
 UI.
 
@@ -178,7 +178,7 @@ if the user selects a new scroll point it will move. When a scroll point is
 selected, if the scrollable region found by the Autoclick component extension
 is large enough, the scroll bubble will be anchored near the scroll point
 itself, similarly to the way the context menu is anchored near the cursor on
-a right click. When the scrollable region is small, the scroll bubble will be 
+a right click. When the scrollable region is small, the scroll bubble will be
 anchored to the closest side of the scrollable region to the scroll point, as
 long as there is space for it on that side.
 
@@ -188,10 +188,10 @@ The AutomaticController cannot generate synthetic click events over the
 bubbles, because that would cause context and focus changes. For example, if
 the user has a drop-down menu open, clicking the autoclick menu bubble will
 cause the drop-down to close. Instead, the AutoclickController must check to
-see if an event will take place over a bubble menu, and if so, request that 
-AutoclickMenuBubbleController forward the event to the bubble via 
+see if an event will take place over a bubble menu, and if so, request that
+AutoclickMenuBubbleController forward the event to the bubble via
 AutoclickMenuBubbleController::ClickOnBubble. This generates a synthetic mouse
-event which does not propagate through the system, so there is no focus or 
+event which does not propagate through the system, so there is no focus or
 context change, allowing users to continue to interact with whatever was on
 screen.
 
diff --git a/chromium/docs/accessibility/chromevox_on_desktop_linux.md b/chromium/docs/accessibility/chromevox_on_desktop_linux.md
index c0975f7b840..13710905569 100644
--- a/chromium/docs/accessibility/chromevox_on_desktop_linux.md
+++ b/chromium/docs/accessibility/chromevox_on_desktop_linux.md
@@ -106,7 +106,8 @@ cd ~
 git clone https://chromium.googlesource.com/chromiumos/third_party/espeak-ng
 cd espeak-ng
 git checkout chrome
-sudo cp -r chrome-extension /usr/share/chromeos-assets/speech_synthesis/espeak-ng
+sudo mkdir -p /usr/share/chromeos-assets/speech_synthesis/espeak-ng
+sudo cp -r chrome-extension/* /usr/share/chromeos-assets/speech_synthesis/espeak-ng
 ```
 
 ## Braille
diff --git a/chromium/docs/accessibility/overview.md b/chromium/docs/accessibility/overview.md
index 7ab969bbb98..ca77b707cbe 100644
--- a/chromium/docs/accessibility/overview.md
+++ b/chromium/docs/accessibility/overview.md
@@ -459,9 +459,9 @@ layer translates WebAXObjects into [AXContentNodeData], which is a subclass of
 cross-platform accessibility tree. The translation is implemented in
 [BlinkAXTreeSource]. This translation happens on the renderer side, so the
 ui::AXNodeData tree now needs to be sent to the browser, which is done by
-sending [AccessibilityHostMsg_EventParams] with the payload being serialized
-delta-updates to the tree, so that changes that happen on the renderer side can
-be reflected on the browser side.
+calling the remote method [ax.mojom.RenderAccessibilityHost::HandleAXEvents()]
+with the payload being serialized delta-updates to the tree, so that changes
+that happen on the renderer side can be reflected on the browser side.
 
 On the browser side, these IPCs are received by [RenderFrameHostImpl], and then
 usually forwarded to [BrowserAccessibilityManager] which is responsible for:
@@ -477,8 +477,11 @@ usually forwarded to [BrowserAccessibilityManager] which is responsible for:
 3. Dispatching incoming accessibility actions to the appropriate recipient, via
    [BrowserAccessibilityDelegate]. For messages destined for a renderer,
    [RenderFrameHostImpl], which is a BrowserAccessibilityDelegate, is
-   responsible for sending appropriate `AccessibilityMsg_Foo` IPCs to the
-   renderer, where they will be received by [RenderAccessibilityImpl].
+   responsible for calling the remote method
+   [ax.mojom.RenderAccessibility.PerformAction()], implemented by the renderer,
+   with the appropriate payload (of type [ax.mojom.AXActionData]). This IPC call
+   will be received by [RenderAccessibilityManager], which will then relay on
+   the [RenderAccessibilityImpl] where the actual logic is implemented.
 
 On Chrome OS, RenderFrameHostImpl does not route events to
 BrowserAccessibilityManager at all, since there is no platform screenreader
@@ -507,7 +510,9 @@ which is renderer-side code, and in JavaScript by the [automation API]. The API
 is defined by [automation.idl], which must be kept synchronized with
 [ax_enums.mojom].
 
-[AccessibilityHostMsg_EventParams]: https://cs.chromium.org/chromium/src/content/common/accessibility_messages.h?sq=package:chromium&l=75
+[ax.mojom.AXActionData]: https://source.chromium.org/chromium/chromium/src/+/master:ui/accessibility/mojom/ax_action_data.mojom;l=13
+[ax.mojom.RenderAccessibilityHost::HandleAXEvents()]: https://source.chromium.org/chromium/chromium/src/+/master:content/common/render_accessibility.mojom;l=47
+[ax.mojom.RenderAccessibility.PerformAction()]: https://source.chromium.org/chromium/chromium/src/+/master:content/common/render_accessibility.mojom;l=86
 [AutomationInternalCustomBindings]: https://cs.chromium.org/chromium/src/extensions/renderer/api/automation/automation_internal_custom_bindings.h
 [AXContentNodeData]: https://cs.chromium.org/chromium/src/content/common/ax_content_node_data.h
 [AXLayoutObject]: https://cs.chromium.org/chromium/src/third_party/blink/renderer/modules/accessibility/ax_layout_object.h
@@ -525,6 +530,7 @@ is defined by [automation.idl], which must be kept synchronized with
 [ViewAccessibility]: https://cs.chromium.org/chromium/src/ui/views/accessibility/view_accessibility.h
 [Node]: https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/dom/node.h
 [RenderAccessibilityImpl]: https://cs.chromium.org/chromium/src/content/renderer/accessibility/render_accessibility_impl.h
+[RenderAccessibilityManager]: https://source.chromium.org/chromium/chromium/src/+/master:content/renderer/accessibility/render_accessibility_manager.h
 [RenderFrameHostImpl]: https://cs.chromium.org/chromium/src/content/browser/frame_host/render_frame_host_impl.h
 [ui::AXNodeData]: https://cs.chromium.org/chromium/src/ui/accessibility/ax_node_data.h
 [WebAXObject]: https://cs.chromium.org/chromium/src/third_party/blink/public/web/web_ax_object.h
diff --git a/chromium/docs/accessibility/reader_mode.md b/chromium/docs/accessibility/reader_mode.md
new file mode 100644
index 00000000000..da1491856c5
--- /dev/null
+++ b/chromium/docs/accessibility/reader_mode.md
@@ -0,0 +1,167 @@
+# Reader Mode on Desktop Platforms
+Reader Mode is an accessibility feature which offers a simplified version of the
+original page that focuses on the “core” text, stripping out extraneous images,
+UI, scripts, and other elements. It is launched on Android as “Simplified View”.
+
+Reader Mode is based on the DOM distiller project which provides functionality
+for simplifying a webpage. This document focuses on how the
+[DOM distiller](https://chromium.googlesource.com/chromium/dom-distiller)
+project is integrated into Chrome on Desktop.
+
+## Overview
+
+Desktop Reader Mode is hidden behind a
+[base::Feature](https://source.chromium.org/chromium/chromium/src/+/master:components/dom_distiller/core/dom_distiller_features.cc)
+flag, ‘enable-reader-mode’. To run Chrome with Reader Mode, set the “Enable
+Reader Mode” flag to “Enabled” in chrome://flags or start Chrome with
+--enable-feature=”ReaderMode”.
+
+### Code Locations
+
+Most of Reader Mode code is in components/dom_distiller (see the
+[DOM distiller project](https://chromium.googlesource.com/chromium/dom-distiller)).
+It is tied into Chrome via hooks in chrome/browser/dom_distiller (Desktop) and
+chrome/browser/android/dom_distiller (Android).
+
+### Tests
+
+Most Reader Mode tests are in components_unittests or components_browsertests.
+Tests for integration with Chrome Desktop are in browser_tests, including tests
+of ReaderModeIconView and dom_distiller/tab_utils.h.
+
+### Bugs
+
+Reader Mode bugs should be filed under
+[UI>Browser>ReaderMode](https://bugs.chromium.org/p/chromium/issues/list?q=component:UI%3EBrowser%3EReaderMode)
+in crbug.com.
+
+## How Reader Mode works in Desktop Chrome
+
+### Deciding whether to offer Reader Mode
+
+Reader Mode classifies all pages visited by the user as “distillable” or
+“not distillable”. A page is distillable, roughly speaking, when it has a
+http or https scheme, contains an article and when DOM Distiller is likely to
+accurately extract its core content. For example, many news articles are
+distillable because they mostly consist of a single column of core text. In
+contrast, the Wikipedia main page is not distillable because it contains several
+unrelated text areas that are of roughly equal importance.
+
+The [DistillabilityAgent](https://cs.chromium.org/chromium/src/components/dom_distiller/content/renderer/distillability_agent.h),
+located in the renderer process, examines the page contents whenever the
+compositor makes a meaningful change to the layout, which happens 1 to 3 times
+as the page loads. It then uses one of several different heuristics to determine
+whether the page is distillable or not. The browser receives the result obtained
+by the DistillabilityAgent for a given web contents via the
+[DistillabilityService](https://cs.chromium.org/chromium/src/components/dom_distiller/content/common/mojom/distillability_service.mojom),
+which is wrapped by a helper class, the
+[DistillabilityDriver](https://cs.chromium.org/chromium/src/components/dom_distiller/content/browser/distillability_driver.h).
+The DistillabilityDriver packages this information as a
+[DistillabilityResult](https://cs.chromium.org/chromium/src/components/dom_distiller/content/browser/distillable_page_utils.h),
+forwards it to all registered observers, and caches it.
+
+### Toggling Reader Mode
+Users can toggle reader mode using an omnibox icon or an option, Toggle Reader
+Mode, in the “customize and control Chrome” menu, both of which execute
+BrowserCommands [ToggleDistilledView()](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/browser_commands.cc;bpv=1;bpt=1;l=1364?q=browser_commands%20dom_distiller&ss=chromium%2Fchromium%2Fsrc).
+
+[ReaderModeIconView](https://cs.chromium.org/chromium/src/chrome/browser/ui/views/reader_mode/reader_mode_icon_view.h)
+is a DistillabilityObserver and sets its visibility based on the latest result
+for the currently active web contents. Reader Mode on desktop only considers
+whether the page is a distilled page, or, if not, the field
+DistillabilityResult::is_distillable when deciding whether to display the icon;
+the other fields are ignored. The icon’s visibility is updated when
+ * the user navigates to a new page within the same tab,
+ * the user switches tabs, and
+ * when a new distillability result is available.
+
+### Representing Reader Mode in the tab strip and omnibox
+Reader Mode should be considered a way of viewing a page, rather than a separate
+page to users. For this reason, we display most of the original page’s
+information:
+
+ * The omnibox displays the original page URL, minus the scheme.
+    * The actual URL of the Reader Mode page is still “chrome-distiller://”
+    which is still returned from WebContents::GetLastCommittedURL() and
+    WebContents::GetVisibleURL().
+    * A special case in LocationBarModel::GetFormattedURL converts from
+    “chrome-distiller://” URLs to the original URL minus the scheme
+      * However, if a user types in an invalid chrome-distiller:// URL,
+      it will be displayed in the omnibox, because it doesn’t correspond to any
+      article.
+    * Users cannot copy the hidden “chrome-distiller://” URLs, instead
+    OmniboxEditModel::AdjustTextForCopy converts Reader Mode URLs to their
+    original URLs, if the chrome-distiller:// url encodes a valid original URL.
+ * The security badge shows a Reader Mode-specific icon plus the phrase
+ “Reader Mode”
+    * SecurityState’s GetSecurityLevel returns SecurityLevel::NONE for
+    “chrome-distiller://” scheme pages. Distilled pages should not contain forms,
+    payment handlers, or other JS from the original URL, so they won’t be
+    affected by downgraded security level.
+ * The tab strip displays the original page’s favicon.
+    * ChromeFaviconClient is used to check if a URL is a Reader Mode page and
+    if so gets the original page’s URL to use for fetching the favicon.
+ * Bookmarking the distilled page actually bookmarks the original article
+    * BookmarkUtils GetURLToBookmark and GetURLAndTitleToBookmark both check for
+    whether a page is a distilled page before extracting the original page
+    title/URL from the distilled URL.
+
+The page title is the original page title with “- Reader Mode” added to the end.
+For example, if the original page’s title is “An Interesting Article - A
+Website”, the tab strip will display “An Interesting Article - A Website -
+Reader Mode” when the user activates Reader Mode.
+
+#### Representing page security
+
+On desktop Reader Mode there are strict security checks in place to ensure that
+SecurityLevel::NONE is appropriate. This includes:
+ * Only pages with SecurityLevel::SECURE are considered distillable (checked in
+ DistillabilityDriver::OnDistillability)
+ * Subresources with mixed content are not loaded on Reader Mode pages (enforced
+ in DomDistillerViewerSource::StartDataRequest)
+ * Subresources with certificate errors are not loaded on Reader Mode pages
+ (checked in ChromeContentBrowserClient::ShouldDenyRequestOnCertificateError)
+On Android, we do not show a custom security indicator or have a specific
+SecurityLevel, so it is not necessary to do such strict checking.
+
+### Extracting core page content
+Reader Mode uses Chrome’s built-in DOM Distiller to generate the simplified
+version of the page. See the
+[DOM Distiller project](https://github.com/chromium/dom-distiller) on GitHub and
+this (Google-internal) [presentation](https://docs.google.com/presentation/d/1etC7ghAU89ec-UeJQ90q4KbHJHH6owfl7OactTcJvCc/edit#slide=id.p)
+for more information on how DOM Distiller works and how to debug it. From
+Chrome’s perspective, distilling the page to extract core page content can be
+considered a black box.
+
+In short, content is extracted from the fully rendered article via Javascript
+(specifically from the compiled Javascript file built from DOM Distiller,
+[domdistiller.js](https://source.chromium.org/chromium/chromium/src/+/master:third_party/dom_distiller_js/dist/js/domdistiller.js))
+into a DistilledPageProto.
+
+The DOM Distiller retrieves the currently loaded document’s DOM and converts it
+to a simplified HTML string using the following process:
+ 1. Remove hidden elements from the set of elements to examine.
+ 2. Identify important elements by passing them through a series of filters,
+ marking elements as “content” or “not content” based on factors such as number
+ of words in the element, location on the page relative to other elements, and
+ image size.
+ 3. Create the output HTML by concatenating the string representation of
+ elements marked as “content”.
+
+The distilled page is served on a locally stored file with a URI composed of
+the following:
+ * Scheme: chrome-distiller://
+ * Host: a random string plus a hash of the entire original URL
+ * Query: parameters giving distillation start time and the original page URL
+ and title
+
+### Displaying Reader Mode Pages
+
+A [DistilledPageProto](https://source.chromium.org/chromium/chromium/src/+/master:components/dom_distiller/core/proto/distilled_page.proto)
+is created for each page distilled, and is used to generate the HTML of the
+distilled page.
+
+Pages are loaded by
+[DomDistillerViewerSource](https://source.chromium.org/chromium/chromium/src/+/master:components/dom_distiller/content/browser/dom_distiller_viewer_source.h),
+which serves the HTML and resources for viewing pages. After the DOM is
+initially loaded, the contents are populated via Javascript.
\ No newline at end of file
diff --git a/chromium/docs/accessibility/relnotes.md b/chromium/docs/accessibility/relnotes.md
new file mode 100644
index 00000000000..016495ebe2b
--- /dev/null
+++ b/chromium/docs/accessibility/relnotes.md
@@ -0,0 +1,46 @@
+# Accessibility Release Notes
+
+## TL;DR
+Any change to accessibility-related files requires specifying an **AX-Relnotes**
+field within the commit message, which describes the user-impacts the change
+will have. Please see below for some examples of what this could look like:
+
+* 'AX-Relnotes: ChromeVox now supports ...'
+* 'AX-Relnotes: Fixed an issue where ... happened because of ...'
+* 'AX-Relnotes: n/a', if the change has no user-facing effects.
+
+If your change has user-impact, but is behind a feature flag, please use ‘n/a’.
+At the time you remove the feature flag, the AX-Relnotes should mention that the
+feature is being launched.
+
+## What Are Release Notes
+Every release cycle, the Chrome & Chrome OS Accessibility Team compiles release
+notes for users, which detail any user-facing changes that have been made in
+the upcoming release. These help our users stay informed about the features
+and bugs our team works on, and are utilized by multiple testing teams.
+
+## The Release Notes Process
+Release notes are a collaborative effort and usually involve two or three team
+members who own the process. The process is as follows:
+1. One owner generates a list of commits for the release and pastes the output
+in a shared Google Document.
+2. The commits are split evenly among the owners.
+3. Each owner parses their assigned commits, removing irrelevant information,
+summarizing important content, contacting developers for clarification, and
+categorizing commits with user-impact.
+4. Once all commits have been categorized or deleted, one owner forwards the
+release notes to the team's PgMs.
+5. The PgMs take a final pass over the document, then forward it to relevant
+stakeholders.
+
+## Why AX-Relnotes
+We require our developers to include an AX-Relnotes field in their commit
+messages to make the release notes process more distributed and accurate.
+Developers have the most context about how their changes affect users, and
+having developers summarize their changes saves time and effort for the
+release notes owners.
+
+## Questions?
+If you have any questions regarding accessibility release notes that have not
+been answered in this document, please contact a member of
+ui/accessibility/OWNERS.
\ No newline at end of file
diff --git a/chromium/docs/adding_to_third_party.md b/chromium/docs/adding_to_third_party.md
index e8e45a4a186..72f32f67a5f 100644
--- a/chromium/docs/adding_to_third_party.md
+++ b/chromium/docs/adding_to_third_party.md
@@ -138,8 +138,10 @@ are typically allocated only when a vulnerability is found. You should follow
 the version number convention such that, when that does occur in future, we'll
 be notified. If no CPE is available, please specify "unknown".
 
-You may sometimes find that your package lacks a CPE, in which case this line
-can be omitted. If it does have a CPE, though, you should specify it.
+If you're using a patched or modified version which is halfway between two
+public versions, please "round downwards" to the lower of the public versions
+(it's better for us to be notified of false-positive vulnerabilities than
+false-negatives).
 
 ### Add a LICENSE file and run related checks
 
diff --git a/chromium/docs/android_dynamic_feature_modules.md b/chromium/docs/android_dynamic_feature_modules.md
index e0ae42135b7..3e5dd23d732 100644
--- a/chromium/docs/android_dynamic_feature_modules.md
+++ b/chromium/docs/android_dynamic_feature_modules.md
@@ -44,7 +44,7 @@ as resources. This section walks you through creating the module target in our
 build system.
 
 First, create the file
-`//chrome/android/features/foo/internal/java/AndroidManifest.xml` and add:
+`//chrome/android/modules/foo/internal/java/AndroidManifest.xml` and add:
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -69,13 +69,13 @@ First, create the file
 ```
 
 Next, create a descriptor configuring the Foo module. To do this, create
-`//chrome/android/features/foo/foo_module.gni` and add the following:
+`//chrome/android/modules/foo/foo_module.gni` and add the following:
 
 ```gn
 foo_module_desc = {
   name = "foo"
   android_manifest =
-      "//chrome/android/features/foo/internal/java/AndroidManifest.xml"
+      "//chrome/android/modules/foo/internal/java/AndroidManifest.xml"
 }
 ```
 
@@ -84,7 +84,7 @@ Then, add the module descriptor to the appropriate descriptor list in
 list:
 
 ```gn
-import("//chrome/android/features/foo/foo_module.gni")
+import("//chrome/android/modules/foo/foo_module.gni")
 ...
 chrome_modern_module_descs += [ foo_module_desc ]
 ```
@@ -107,7 +107,7 @@ this step.
 <!--- TODO(tiborg): Add info about install UI. -->
 Lastly, give your module a title that Chrome and Play can use for the install
 UI. To do this, add a string to
-`//chrome/android/java/strings/android_chrome_strings.grd`:
+`//chrome/browser/ui/android/strings/android_chrome_strings.grd`:
 
 ```xml
 ...
@@ -180,32 +180,26 @@ First, define a module interface for Foo. This is accomplished by adding the
 `@ModuleInterface` annotation to the Foo interface. This annotation
 automatically creates a `FooModule` class that can be used later to install and
 access the module. To do this, add the following in the new file
-`//chrome/android/features/foo/public/java/src/org/chromium/chrome/features/foo/Foo.java`:
+`//chrome/browser/foo/android/java/src/org/chromium/chrome/browser/foo/Foo.java`:
 
 ```java
-package org.chromium.chrome.features.foo;
+package org.chromium.chrome.browser.foo;
 
 import org.chromium.components.module_installer.builder.ModuleInterface;
 
 /** Interface to call into Foo feature. */
-@ModuleInterface(module = "foo", impl = "org.chromium.chrome.features.FooImpl")
+@ModuleInterface(module = "foo", impl = "org.chromium.chrome.browser.FooImpl")
 public interface Foo {
     /** Magical function. */
     void bar();
 }
 ```
 
-*** note
-**Note:** To reflect the separation from "Chrome browser" code, features should
-be defined in their own package name, distinct from the chrome package - i.e.
-`org.chromium.chrome.features.<feature-name>`.
-***
-
 Next, define an implementation that goes into the module in the new file
-`//chrome/android/features/foo/internal/java/src/org/chromium/chrome/features/foo/FooImpl.java`:
+`//chrome/browser/foo/internal/android/java/src/org/chromium/chrome/browser/foo/FooImpl.java`:
 
 ```java
-package org.chromium.chrome.features.foo;
+package org.chromium.chrome.browser.foo;
 
 import org.chromium.base.Log;
 import org.chromium.base.annotations.UsedByReflection;
@@ -231,31 +225,36 @@ if (FooModule.isInstalled()) {
 ```
 
 The interface has to be available regardless of whether the Foo DFM is present.
-Therefore, put those classes into the base module. For this create a list of
-those Java files in
-`//chrome/android/features/foo/public/foo_public_java_sources.gni`:
+Therefore, put those classes into the base module, creating a new public
+build target in: `//chrome/browser/foo/BUILD.gn`:
 
 ```gn
-foo_public_java_sources = [
-  "//chrome/android/features/foo/public/java/src/org/chromium/chrome/features/foo/Foo.java",
-]
+import("//build/config/android/rules.gni")
+
+android_library("java") {
+  sources = [
+    "android/java/src/org/chromium/chrome/browser/foo/Foo.java",
+  ]
+}
 ```
 
-Then add this list to `chrome_java in //chrome/android/BUILD.gn`:
+Then, depend on this target from where it is used as usual. For example, if the
+caller is in `chrome_java in //chrome/android/BUILD.gn`:
 
 ```gn
 ...
-import("//chrome/android/features/foo/public/foo_public_java_sources.gni")
-...
 android_library("chrome_java") {
-  ...
-  sources += foo_public_java_sources
+  deps =[
+    ...
+    "//chrome/browser/foo:java",
+    ...
+  ]
 }
 ...
 ```
 
 The actual implementation, however, should go into the Foo DFM. For this
-purpose, create a new file `//chrome/android/features/foo/internal/BUILD.gn` and
+purpose, create a new file `//chrome/browser/foo/internal/BUILD.gn` and
 make a library with the module Java code in it:
 
 ```gn
@@ -264,15 +263,17 @@ import("//build/config/android/rules.gni")
 android_library("java") {
   # Define like ordinary Java Android library.
   sources = [
-    "java/src/org/chromium/chrome/features/foo/FooImpl.java",
+    "android/java/src/org/chromium/chrome/browser/foo/FooImpl.java",
     # Add other Java classes that should go into the Foo DFM here.
   ]
-  # Put other Chrome libs into the classpath so that you can call into the rest
-  # of Chrome from the Foo DFM.
   deps = [
     "//base:base_java",
+    # Put other Chrome libs into the classpath so that you can call into them
+    # from the Foo DFM.
+    "//chrome/browser/bar:java",
+    # The module can depend even on `chrome_java` due to factory magic, but this
+    # is discouraged. Consider passing a delegate interface in instead.
     "//chrome/android:chrome_java",
-    # etc.
     # Also, you'll need to depend on any //third_party or //components code you
     # are using in the module code.
   ]
@@ -280,20 +281,20 @@ android_library("java") {
 ```
 
 Then, add this new library as a dependency of the Foo module descriptor in
-`//chrome/android/features/foo/foo_module.gni`:
+`//chrome/android/modules/foo/foo_module.gni`:
 
 ```gn
 foo_module_desc = {
   ...
   java_deps = [
-    "//chrome/android/features/foo/internal:java",
+    "//chrome/browser/foo/internal:java",
   ]
 }
 ```
 
 Finally, tell Android that your module is now containing code. Do that by
 removing the `android:hasCode="false"` attribute from the `<application>` tag in
-`//chrome/android/features/foo/internal/java/AndroidManifest.xml`. You should be
+`//chrome/android/modules/foo/internal/java/AndroidManifest.xml`. You should be
 left with an empty tag like so:
 
 ```xml
@@ -311,7 +312,7 @@ logcat. Yay!
 
 You can add a third-party native library (or any standalone library that doesn't
 depend on Chrome code) by adding it as a loadable module to the module descriptor in
-`//chrome/android/features/foo/foo_module.gni`:
+`//chrome/android/moduiles/foo/foo_module.gni`:
 
 ```gn
 foo_module_desc = {
@@ -409,8 +410,8 @@ component("foo") {
   ]
   deps = [
     ":jni_registration",
-    "//chrome/android/features/foo/internal:native",
     "//base",
+    "//chrome/browser/foo/internal:native",
   ]
 
   # Instruct the compiler to flag exported entrypoint function as belonging in
@@ -426,7 +427,7 @@ component("foo") {
 # specified Java target, and not all its transitive deps (which could include
 # the base module).
 generate_jni_registration("jni_registration") {
-  targets = [ "//chrome/android/features/foo/internal:java" ]
+  targets = [ "//chrome/browser/foo/internal:java" ]
   header_output = "$target_gen_dir/jni_registration.h"
   namespace = "foo"
   no_transitive_deps = true
@@ -445,11 +446,11 @@ Now, over to the implementation of the module. These are the parts that
 shouldn't know or care whether they're living in a module or not.
 
 Add a stub implementation in
-`//chrome/android/features/foo/internal/foo_impl.cc`:
+`//chrome/browser/foo/internal/android/foo_impl.cc`:
 
 ```c++
 #include "base/logging.h"
-#include "chrome/android/features/foo/internal/jni_headers/FooImpl_jni.h"
+#include "chrome/browser/foo/internal/jni_headers/FooImpl_jni.h"
 
 static int JNI_FooImpl_Execute(JNIEnv* env) {
   LOG(INFO) << "Running foo feature code!";
@@ -458,7 +459,7 @@ static int JNI_FooImpl_Execute(JNIEnv* env) {
 ```
 
 And, the associated build config in
-`//chrome/android/features/foo/internal/BUILD.gn`:
+`//chrome/browser/foo/internal/BUILD.gn`:
 
 ```gn
 import("//build/config/android/rules.gni")
@@ -467,7 +468,7 @@ import("//build/config/android/rules.gni")
 
 source_set("native") {
   sources = [
-    "foo_impl.cc",
+    "android/foo_impl.cc",
   ]
 
   deps = [
@@ -478,7 +479,7 @@ source_set("native") {
 
 generate_jni("jni_headers") {
   sources = [
-    "java/src/org/chromium/chrome/features/foo/FooImpl.java",
+    "android/java/src/org/chromium/chrome/browser/foo/FooImpl.java",
   ]
 }
 ```
@@ -503,8 +504,8 @@ Finally, augment the module descriptor in
 foo_module_desc = {
   ...
   native_deps = [
-    "//chrome/android/features/foo/internal:native",
     "//chrome/android/modules/foo/internal:native",
+    "//chrome/browser/foo/internal:native",
   ]
   load_native_on_get_impl = true
 }
@@ -542,7 +543,7 @@ In this section we will add the required build targets to add Android resources
 to the Foo DFM.
 
 First, add a resources target to
-`//chrome/android/features/foo/internal/BUILD.gn` and add it as a dependency on
+`//chrome/browser/foo/internal/BUILD.gn` and add it as a dependency on
 Foo's `java` target in the same file:
 
 ```gn
@@ -550,7 +551,7 @@ Foo's `java` target in the same file:
 android_resources("java_resources") {
   # Define like ordinary Android resources target.
   ...
-  custom_package = "org.chromium.chrome.features.foo"
+  custom_package = "org.chromium.chrome.browser.foo"
 }
 ...
 android_library("java") {
@@ -564,7 +565,7 @@ android_library("java") {
 To add strings follow steps
 [here](http://dev.chromium.org/developers/design-documents/ui-localization) to
 add new Java GRD file. Then create
-`//chrome/android/features/foo/internal/java/strings/android_foo_strings.grd` as
+`//chrome/browser/foo/internal/android/resources/strings/android_foo_strings.grd` as
 follows:
 
 ```xml
@@ -599,13 +600,13 @@ follows:
 ```
 
 Then, create a new GRD target and add it as a dependency on `java_resources` in
-`//chrome/android/features/foo/internal/BUILD.gn`:
+`//chrome/browser/foo/internal/BUILD.gn`:
 
 ```gn
 ...
 java_strings_grd("java_strings_grd") {
   defines = chrome_grit_defines
-  grd_file = "java/strings/android_foo_strings.grd"
+  grd_file = "android/resources/strings/android_foo_strings.grd"
   outputs = [
     "values-am/android_foo_strings.xml",
     # Here, too, list output files for other supported languages.
@@ -616,23 +617,23 @@ java_strings_grd("java_strings_grd") {
 android_resources("java_resources") {
   ...
   deps = [":java_strings_grd"]
-  custom_package = "org.chromium.chrome.features.foo"
+  custom_package = "org.chromium.chrome.browser.foo"
 }
 ...
 ```
 
 You can then access Foo's resources using the
-`org.chromium.chrome.features.foo.R` class. To do this change
-`//chrome/android/features/foo/internal/java/src/org/chromium/chrome/features/foo/FooImpl.java`
+`org.chromium.chrome.browser.foo.R` class. To do this change
+`//chrome/browser/foo/internal/android/java/src/org/chromium/chrome/browser/foo/FooImpl.java`
 to:
 
 ```java
-package org.chromium.chrome.features.foo;
+package org.chromium.chrome.browser.foo;
 
 import org.chromium.base.ContextUtils;
 import org.chromium.base.Log;
 import org.chromium.base.annotations.UsedByReflection;
-import org.chromium.chrome.features.foo.R;
+import org.chromium.chrome.browser.foo.R;
 
 @UsedByReflection("FooModule")
 public class FooImpl implements Foo {
@@ -703,8 +704,8 @@ for a DFM's native resources:
 ```gn
 foo_module_desc = {
   ...
-  paks = [ "$root_gen_dir/chrome/android/features/foo/internal/foo_resourcess.pak" ]
-  pak_deps = [ "//chrome/android/features/foo/internal:foo_paks" ]
+  paks = [ "$root_gen_dir/chrome/browser/foo/internal/foo_resourcess.pak" ]
+  pak_deps = [ "//chrome/browser/foo/internal:foo_paks" ]
   load_native_on_get_impl = true
 }
 ```
@@ -800,6 +801,12 @@ installing it as a true split. We therefore recommend that you always test both
 install methods.
 ***
 
+*** note
+To simplify development, the DevUI DFM (dev_ui) is installed by default, i.e.,
+`-m dev_ui` is implied by default. This is overridden by:
+* `--no-module dev_ui`, to test error from missing DevUI,
+* `-f dev_ui`, for fake module install.
+***
 
 #### Deferred install
 
@@ -820,7 +827,7 @@ Conditional install means the DFM will be installed automatically upon first
 installing or updating Chrome if the device supports a particular feature.
 Conditional install is configured in the module's manifest. To install your
 module on all Daydream-ready devices for instance, your
-`//chrome/android/features/foo/internal/java/AndroidManifest.xml` should look
+`//chrome/android/modules/foo/internal/java/AndroidManifest.xml` should look
 like this:
 
 ```xml
@@ -881,7 +888,7 @@ template("chrome_public_common_apk_or_module_tmpl") {
     ...
     if (_target_type != "android_app_bundle_module") {
       deps += [
-        "//chrome/android/features/foo/internal:java",
+        "//chrome/browser/foo/internal:java",
       ]
     }
   }
diff --git a/chromium/docs/android_emulator.md b/chromium/docs/android_emulator.md
index ecbfd06bc41..99eb1037354 100644
--- a/chromium/docs/android_emulator.md
+++ b/chromium/docs/android_emulator.md
@@ -10,7 +10,112 @@ You need to target the correct architecture via GN args:
 target_cpu = "x86"  # or "x64" if you have an x86_64 emulator
 ```
 
-## Creating an Emulator Image
+## Running an Emulator
+
+### Using Prebuilt CIPD packages
+
+Chromium has a set of prebuilt images stored as CIPD packages. These are used
+by various builders to run tests on the emulator. Their configurations are
+currently stored in `//tools/android/avd/proto`.
+
+| File | Builder |
+|:----:|:-------:|
+| `tools/android/avd/proto/generic_android28.textpb` | [android-pie-x86-rel][android-pie-x86-rel] |
+
+You can use these configuration files to run the same emulator images locally.
+
+[android-pie-x86-rel]: https://ci.chromium.org/p/chromium/builders/ci/android-pie-x86-rel
+
+#### Running via the test runner
+
+The android test runner can run emulator instances on its own. In doing so, it
+starts the emulator instances, runs tests against them, and then shuts them
+down. This is how builders run the emulator.
+
+##### Options
+
+ * `--avd-config`
+
+    To have the test runner run an emulator instance, use `--avd-config`:
+
+    ```
+      $ out/Debug/bin/run_base_unittests \
+          --avd-config tools/android/avd/proto/generic_android28.textpb
+    ```
+
+ * `--emulator-count`
+
+    The test runner will launch one instance by default. To have it run multiple
+    instances, use `--emulator-count`:
+
+    ```
+      $ out/Debug/bin/run_base_unittests \
+          --avd-config tools/android/avd/proto/generic_android28.textpb \
+          --emulator-count 4
+    ```
+
+ * `--emulator-window`
+
+    The test runner runs the emulator in headless mode by default. To have it run
+    with a window, use `--emulator-window`:
+
+    ```
+      $ out/Debug/bin/run_base_unittests \
+          --avd-config tools/android/avd/proto/generic_android28.textpb \
+          --emulator-window
+    ```
+
+#### Running standalone
+
+The test runner will set up and tear down the emulator on each invocation.
+To manage emulator lifetime independently, use `tools/android/avd/avd.py`.
+
+**NOTE**: You'll first need to install the emulator configuration you intend to
+use:
+
+  ```
+    $ tools/android/avd/avd.py install \
+        --avd-config tools/android/avd/proto/generic_android28.textpb
+  ```
+
+##### Options
+
+ * `--avd-config`
+
+    This behaves the same as it does for the test runner.
+
+    ```
+      $ tools/android/avd/avd.py start \
+          --avd-config tools/android/avd/proto/generic_android28.textpb
+    ```
+
+    > Note: `avd.py start` will start an emulator instance and then terminate.
+    > To shut down the emulator, use `adb emu stop`.
+
+ * `--emulator-window`
+
+    Like the test runner, `avd.py` runs the emulator in headless mode by default.
+    To have it run with a window, use `--emulator-window`:
+
+    ```
+      $ tools/android/avd/avd.py start \
+          --avd-config tools/android/avd/proto/generic_android28.textpb \
+          --emulator-window
+    ```
+
+ * `--no-read-only`
+
+    `avd.py` runs the emulator in read-only mode by default. To run a modifiable
+    emulator, use `--no-read-only`:
+
+    ```
+      $ tools/android/avd/avd.py start \
+          --avd-config tools/android/avd/proto/generic_android28.textpb \
+          --no-read-only
+    ```
+
+### Using Your Own Emulator Image
+
 By far the easiest way to set up emulator images is to use Android Studio.
 If you don't have an [Android Studio project](android_studio.md) already, you
 can create a blank one to be able to reach the Virtual Device Manager screen.
@@ -22,11 +127,15 @@ Where files live:
  * Emulator configs and data partition images are stored within
    `~/.android/avd/`.
 
-### Choosing a Skin
+#### Creating an Image
+
+##### Choosing a Skin
+
 Choose a skin with a small screen for better performance (unless you care about
 testing large screens).
 
-### Choosing an Image
+##### Choosing an Image
+
 Android Studio's image labels roughly translate to the following:
 
 | AVD "Target" | Virtual Device Configuration tab | GMS? | Build Properties |
@@ -40,12 +149,14 @@ Android Studio's image labels roughly translate to the following:
 Images** tab in the Virtual Device Configuration wizard.
 ***
 
-### Configuration
+##### Configuration
+
 "Show Advanced Settings" > scroll down:
 * Set internal storage to 4000MB (component builds are really big).
 * Set SD card to 1000MB (our tests push a lot of files to /sdcard).
 
-### Known Issues
+##### Known Issues
+
  * Our test & installer scripts do not work with pre-MR1 Jelly Bean.
  * Component builds do not work on pre-KitKat (due to the OS having a max
    number of shared libraries).
@@ -55,7 +166,9 @@ Images** tab in the Virtual Device Configuration wizard.
    * Can often be fixed by editing `~/.android/avd/YOUR_DEVICE/config.ini`.
      * Look for `hw.sdCard=no` and set it to `yes`
 
-## Starting an Emulator from the Command Line
+
+#### Starting an Emulator from the Command Line
+
 Refer to: https://developer.android.com/studio/run/emulator-commandline.html.
 
 *** promo
@@ -67,7 +180,8 @@ Ctrl-C will gracefully close an emulator.
 provide tab completion for the `emulator` command line tool.
 ***
 
-### Basic Command Line Use
+#### Basic Command Line Use
+
 ```shell
 $ # List virtual devices that you've created:
 $ ~/Android/Sdk/emulator/emulator -list-avds
@@ -75,7 +189,8 @@ $ # Start a named device:
 $ ~/Android/Sdk/emulator/emulator @EMULATOR_ID
 ```
 
-### Running a Headless Emulator
+#### Running a Headless Emulator
+
 You can run an emulator without creating a window on your desktop (useful for
 `ssh`):
 ```shell
@@ -84,7 +199,8 @@ $ # This also works for new enough emulator builds:
 $ ~/Android/Sdk/emulator/emulator-headless @EMULATOR_ID
 ```
 
-### Running Multiple Emulators
+#### Running Multiple Emulators
+
 Tests are automatically sharded amongst available devices. If you run multiple
 emulators, then running test suites becomes much faster. Refer to the
 "Multiple AVD instances" section of these [emulator release notes](
@@ -97,7 +213,8 @@ $ # Start 12 emulators. More than 10 requires disabling audio on some OS's. Redu
 $ ( for i in $(seq 12); do ~/Android/Sdk/emulator/emulator @EMULATOR_ID -read-only -no-audio -cores 2 & done; wait )
 ```
 
-### Writable system partition
+#### Writable system partition
+
 Unlike physical devices, an emulator's `/system` partition cannot be modified by
 default (even on rooted devices). If you need to do so (such as to remove a
 system app), you can start your emulator like so:
diff --git a/chromium/docs/branch_sheriff.md b/chromium/docs/branch_sheriff.md
index ea8c21ad15d..62b1d8a3886 100644
--- a/chromium/docs/branch_sheriff.md
+++ b/chromium/docs/branch_sheriff.md
@@ -56,13 +56,16 @@ Once you've done that, you'll be able to check out branches:
 ```
 
 To determine the appropriate branch number, you can either use
-[chromiumdash](#chromiumdash) or check [milestone.json][milestone-json] directly.
+[chromiumdash](#chromiumdash) or check [milestone.json][milestone-json]
+directly.
 
 ### Findit
+
 As FindIt is not available on branches, one way to try to find culprits is using
-`git bisect` locally and upload changes to a gerrit CL and run the needed trybots
-to check. This is especially useful when the errors are not reproducible on your
-local builds or you don't have the required hardware to build the failed tests.
+`git bisect` locally and upload changes to a gerrit CL and run the needed
+trybots to check. This is especially useful when the errors are not reproducible
+on your local builds or you don't have the required hardware to build the failed
+tests.
 
 ### Flaky tests
 
@@ -81,15 +84,22 @@ relevant release TPM as listed on [chromiumdash][chromiumdash-schedule].
 
 ### Sheriff-o-Matic
 
-Use the [branch SoM console][sheriff-o-matic] rather than the main chromium console.
+Use the [branch SoM console][sheriff-o-matic] rather than the main chromium
+console.
 
 ### Consoles
 
-Use the [beta][main-beta] and [stable][main-stable] branch consoles rather than the
-main console. A new console is created for each milestone. They are named
+Use the [beta][main-beta] and [stable][main-stable] branch consoles rather than
+the main console. A new console is created for each milestone. They are named
 "Chromium M## Console" and can be found under the
 [Chromium Project](https://ci.chromium.org/p/chromium).
 
+### Monorail issues (crbug)
+
+Refer and use the
+[Sheriff-Chrome-Release label](https://bugs.chromium.org/p/chromium/issues/list?q=label%3ASheriff-Chrome-Release)
+to find and tag issues that are of importance to Branch sheriffs.
+
 ### Chromiumdash
 
 [chromiumdash][chromiumdash] can help you determine the branch number for a
diff --git a/chromium/docs/cipd.md b/chromium/docs/cipd.md
index ff29c4b14d7..14298411b1e 100644
--- a/chromium/docs/cipd.md
+++ b/chromium/docs/cipd.md
@@ -62,7 +62,33 @@ lay them out like so:
 ### 3. Create a cipd.yaml file
 
 CIPD knows how to create your package based on a .yaml file you provide to it.
-The .yaml file should take the following form:
+This file can either be generated by a GN template, or manually.
+
+#### 3a. Generating cipd.yaml via GN Template:
+
+The `cipd_package_definition` template in [build/cipd/cipd.gni] can be used to
+create the yaml definition as part of Chromium's normal build process. Declare
+a target like:
+```
+cipd_package_definition("my_cipd_package") {
+  package = "path/to/cipd/package"
+  description = "Prebuilt test binary."
+  install_mode = "copy"
+  deps = [ "//path/to:test_binary_target" ]
+  sources = [ "//path/to:test_binary_file" ]
+}
+```
+
+After generating build files, you can then run
+`ninja -C out/Default my_cipd_package`, which creates the .yaml file under
+`out/Default/my_cipd_package/package.yaml`.
+
+[build/cipd/cipd.gni]: https://source.chromium.org/chromium/chromium/src/+/master:build/cipd/cipd.gni
+
+#### 3b. Generating cipd.yaml by hand:
+
+You can also write the .yaml file by hand. The file should take the following
+form:
 
 ```
 # Comments are allowed.
@@ -122,17 +148,13 @@ data:
   - file: foo.jar
 ```
 
-To create a private (Googler-only) package:
-```
-# Map this to //clank/third_party/sample_cipd_dep.
-package: chrome_internal/third_party/sample_cipd_dep
-```
-
-For more information about the package definition spec, see [the code][3].
+For more information about the package definition spec, see [the code].
 
-> **Note:** Committing the .yaml file to the repository isn't required,
-> but it is recommended. Doing so has benefits for visibility and ease of
-> future updates.
+> **Note:** To make the package private (Googler-only), prefix the package name
+> with `chrome_internal`. For example:
+> ```
+> package: chrome_internal/third_party/sample_cipd_dep
+> ```
 
 [the code]: https://chromium.googlesource.com/infra/luci/luci-go/+/master/cipd/client/cipd/builder/pkgdef.go
 
diff --git a/chromium/docs/clang_tool_refactoring.md b/chromium/docs/clang_tool_refactoring.md
index d4e9f94748c..62ec4418d58 100644
--- a/chromium/docs/clang_tool_refactoring.md
+++ b/chromium/docs/clang_tool_refactoring.md
@@ -54,8 +54,10 @@ Other useful references when writing the tool:
 ### Edit serialization format
 ```
 ==== BEGIN EDITS ====
-r:::path/to/file1:::offset1:::length1:::replacement text
-r:::path/to/file2:::offset2:::length2:::replacement text
+r:::path/to/file/to/edit:::offset1:::length1:::replacement text
+r:::path/to/file/to/edit:::offset2:::length2:::replacement text
+r:::path/to/file2/to/edit:::offset3:::length3:::replacement text
+include-user-header:::path/to/file2/to/edit:::-1:::-1:::header/file/to/include.h
 
        ...
 
@@ -64,8 +66,8 @@ r:::path/to/file2:::offset2:::length2:::replacement text
 
 The header and footer are required. Each line between the header and footer
 represents one edit. Fields are separated by `:::`, and the first field must
-be `r` (for replacement). In the future, this may be extended to handle header
-insertion/removal. A deletion is an edit with no replacement text.
+be `r` (for replacement) or `include-user-header`.
+A deletion is an edit with no replacement text.
 
 The edits are applied by [`apply_edits.py`](#Running), which understands certain
 conventions:
diff --git a/chromium/docs/clangd.md b/chromium/docs/clangd.md
index e4e3df0b289..99559663c4a 100644
--- a/chromium/docs/clangd.md
+++ b/chromium/docs/clangd.md
@@ -39,6 +39,14 @@ tools/clang/scripts/generate_compdb.py -p out/Release > compile_commands.json
 Note: the compilation database is not re-generated automatically, you'd need to
 regenerate it manually when you have new files checked in.
 
+If using Windows PowerShell, use the following command instead to set the
+output's encoding to UTF-8 (otherwise Clangd will hit "YAML:1:4: error: Got
+empty plain scalar" while parsing it).
+
+```
+tools/clang/scripts/generate_compdb.py -p out/Release | out-file -encoding utf8 compile_commands.json
+```
+
 3. Optional: build chrome normally. This ensures generated headers exist and are
 up-to-date. clangd will still work without this step, but it may give errors or
 inaccurate results for files which depend on generated headers.
diff --git a/chromium/docs/contributing.md b/chromium/docs/contributing.md
index 1509632f07f..bbaaacd315d 100644
--- a/chromium/docs/contributing.md
+++ b/chromium/docs/contributing.md
@@ -74,6 +74,7 @@ contribution can be accepted:
 - If the author or their company is not listed, the CL should include a new
   AUTHORS entry.
   - Ensure the new entry is reviewed by a reviewer who works for Google.
+  - Contributor License Agreement can be verified by Googlers at http://go/cla.
   - If there is a corporate CLA for the author's company, it must list the
     person explicitly (or the list of authorized contributors must say
     something like "All employees"). If the author is not on their company's
@@ -212,10 +213,23 @@ nearest ancestor OWNERS file.
 - Anybody can review code, but there must be at least one owner for each
   affected directory.
 - If there are multiple reviewers, make it clear what each reviewer is expected
-  to review. Otherwise, people might assume their input is not required or
-  waste time with redundant reviews.
+  to review.
 - `git cl owners` automatically suggests reviewers based on the OWNERS files.
 
+_Note:_ By default, please only select one reviewer for each file (that is, a
+single reviewer may review multiple files, but typically each file only needs
+to be reviewed by one person). It can be tempting to add multiple reviewers so
+that "whoever gets to it first" can review, but this has two common failure
+modes:
+- Reviewer Alpha and Beta both review the CL, resulting in duplicate effort.
+- Out of fear of the above failure case, neither reviewer Alpha nor Beta review
+  the CL.
+
+There are times when requesting multiple reviewers for the same file may be
+desirable - such as when the code is particularly complicated, or when the file
+uses multiple systems and a perspective from each is valuable. In this case,
+please make it explicit that you would like both reviewers to review.
+
 ### Requesting review
 
 Open the change on [the web][crrev]. If you can't find the link, running `git
diff --git a/chromium/docs/enterprise/add_new_policy.md b/chromium/docs/enterprise/add_new_policy.md
index bd6ad7afe2b..d90cd69ff71 100644
--- a/chromium/docs/enterprise/add_new_policy.md
+++ b/chromium/docs/enterprise/add_new_policy.md
@@ -37,9 +37,13 @@ Usually you need a policy when
         sure you get the version and feature flags (such as dynamic_refresh and
         supported_on) right.
     -   Here are the most used attributes. Please note that, all attributes
-        below other than `supported_on` do not change the code behavior.
+        below other than `supported_on` and `default_for_enterprise_users` do
+        not change the code behavior.
         -   `supported_on`: It controls the platform and Chrome milestone the
             policy supports.
+        -   `default_for_enterprise_users`: Its value is applied as a mandatory
+            policy for managed users on Chrome OS unless a different setting is
+            explicitly set.
         -   `dynamic_refresh`: It tells the admin whether the policy value can
             be changed and take effect without re-launching Chrome.
         -   `per_profile`: It tells the admin whether different policy values
@@ -77,7 +81,12 @@ Usually you need a policy when
             If the policy needs additional verification or processing, please
             implement a `ConfigurationPolicyHandler` to do so.
         3.  Test the mapping by adding policy to
-            [policy_test_cases.json](https://cs.chromium.org/chromium/src/chrome/test/data/policy/policy_test_cases.json?q=policy_test_case)
+            [policy_test_cases.json](https://cs.chromium.org/chromium/src/chrome/test/data/policy/policy_test_cases.json?q=policy_test_case).
+        4.  iOS platform has its own
+            [configuration_policy_handler_list_factory.mm](https://source.chromium.org/chromium/chromium/src/+/master:ios/chrome/browser/policy/configuration_policy_handler_list_factory.mm)
+            and
+            [policy_test_cases.json](https://source.chromium.org/chromium/chromium/src/+/master:ios/chrome/test/data/policy/policy_test_cases.json)
+            file.
 4.  Disable the user setting UI when the policy is applied.
     -   If your feature can be controlled by GUI in `chrome://settings`, the
         associated option should be disabled when the policy controlling it is
@@ -271,6 +280,14 @@ everything listed below.
 * [Policy documentation](https://cloud.google.com/docs/chrome-enterprise/policies/)
   will be updated automatically.
 
+## Targeting features at commercial users
+
+The recommended method to target commercial users is to create a policy to
+control the behavior of a feature. You can for example create a feature only
+for consumer users by setting `default_for_enterprise_users` to false; however,
+it should only be used when the default enterprise behavior should be different
+than regular consumer behavior.
+
 ------
 
 ### Additional Notes
diff --git a/chromium/docs/flag_expiry.md b/chromium/docs/flag_expiry.md
index addc261635f..ce7d0e30287 100644
--- a/chromium/docs/flag_expiry.md
+++ b/chromium/docs/flag_expiry.md
@@ -27,21 +27,16 @@ developer will not remove it earlier than this process specifies.
 
 ## The Process
 
-After each milestone's branch point:
-
-1. The flags team chooses a set of flags to begin expiring, from the list
-   produced by `tools/flags/list_flags.py --expired-by $MSTONE`. In the steady
-   state, when there is not a big backlog of flags to remove, this set will be
-   the entire list of flags that are `expired-by $MSTONE`.
-2. The flags team hides the flags in this set by default from `chrome://flags`,
-   and adds a flag `temporary-unexpire-flags-m$MSTONE` and a base::Feature
-   `TemporaryUnexpireFlagsM$MSTONE` which unhide these flags. When hidden from
-   `chrome://flags`, all the expired flags will behave as if unset, so users
-   cannot be stuck with a non-default setting of a hidden flag.
-3. After two further milestones have passed (i.e. at $MSTONE+2 branch), the
-   temporary unhide flag & feature will be removed (meaning the flags are now
-   permanently invisible), and TPMs will file bugs against the listed owners to
-   remove the flags and clean up the backing code.
+The logic in //tools/flags/generate_unexpire_flags.py implements most of this.
+At any given time, if the current value of MAJOR in //chrome/version is $MSTONE,
+the two previous milestones ($MSTONE-1 and $MSTONE-2) are considered recent.
+
+Then:
+1) Flags whose expiration is $MSTONE or higher are not expired
+2) Flags whose expiration is $MSTONE-3 or lower are unconditionally expired
+3) Flags whose expiration is $MSTONE-1 or $MSTONE-2 are expired by default, but
+   can be temporarily unexpired via flags named
+   "temporary-unexpire-flags-M$MSTONE".
 
 There are other elements of this process not described here, such as emails to
 flags-dev@ tracking the status of the process.
diff --git a/chromium/docs/gpu/gpu_pixel_testing_with_gold.md b/chromium/docs/gpu/gpu_pixel_testing_with_gold.md
index e9c072f9ab7..bffb291c5a2 100644
--- a/chromium/docs/gpu/gpu_pixel_testing_with_gold.md
+++ b/chromium/docs/gpu/gpu_pixel_testing_with_gold.md
@@ -172,6 +172,35 @@ the triage link for the problematic image.
 
 [skia crbug]: https://bugs.chromium.org/p/skia
 
+## Inexact Matching
+
+By default, Gold uses exact matching with support for multiple baselines per
+test. This works well for most of the GPU tests, but there are a handful of
+tests such as `Pixel_CSS3DBlueBox` that are prone to noise which causes them to
+need additional triaging at times.
+
+For cases like this, using inexact matching can help, as it allows a comparison
+to pass if there are only minor differences between the produced image and a
+known-good image. Images that pass in this way will be automatically approved
+in Gold, so there is still a record of exactly what was produced.
+
+To enable this functionality, simply add a `matching_algorithm` field to the
+`PixelTestPage` definition for the test (see other uses of this in the file for
+concrete examples).
+
+In order to determine which values to use, you can use the script located at
+`//content/test/gpu/gold_inexact_matching/determine_gold_inexact_parameters.py`.
+
+More complete documentation can be found in the `--help` output of the script,
+but in general:
+* Use the `binary_search` optimization algorithm if you only want to vary
+    a single parameter, e.g. you only want to use a Sobel filter.
+* Use the `local_minima` optimization algorithm if you want to vary multiple
+    parameters, such as using fuzzy diffing + a Sobel filter together.
+* The default boundaries and weights generally work and give good results, but
+    you may need to tune them to better suit your particular test, e.g.
+    increasing the maximum number of differing pixels if your image is large.
+
 ## Working On Gold
 
 ### Modifying Gold And goldctl
diff --git a/chromium/docs/gpu/gpu_testing.md b/chromium/docs/gpu/gpu_testing.md
index 807b42f61b3..a2d9b20470d 100644
--- a/chromium/docs/gpu/gpu_testing.md
+++ b/chromium/docs/gpu/gpu_testing.md
@@ -562,6 +562,13 @@ into:
 
 `https://chrome-gpu-gold.skia.org/search?query=name%3D<test name>`
 
+**NOTE** If you have a grace period active for your test, then Gold will be told
+to ignore results for the test. This is so that it does not comment on unrelated
+CLs about untriaged images if your test is noisy. Images will still be uploaded
+to Gold and can be triaged, but will not show up on the main page's untriaged
+image list, and you will need to enable the "Ignored" toggle at the top of the
+page when looking at the triage page specific to your test.
+
 ## Stamping out Flakiness
 
 It's critically important to aggressively investigate and eliminate the root
diff --git a/chromium/docs/gpu/gpu_testing_bot_details.md b/chromium/docs/gpu/gpu_testing_bot_details.md
index 2d7701d4db7..7255a9ea027 100644
--- a/chromium/docs/gpu/gpu_testing_bot_details.md
+++ b/chromium/docs/gpu/gpu_testing_bot_details.md
@@ -429,21 +429,17 @@ Builder].
         1.  Run [`generate_buildbot_json.py`][generate_buildbot_json.py] to
             regenerate `src/testing/buildbot/chromium.gpu.fyi.json`.
     1. Updates [`ci.star`][ci.star] and its related generated files
-       [`cr-buildbucket.cfg`][cr-buildbucket.cfg] and
-       [`luci-scheduler.cfg`][luci-scheduler.cfg]:
+       [`cr-buildbucket.cfg`][cr-buildbucket.cfg],
+       [`luci-scheduler.cfg`][luci-scheduler.cfg], and
+       ['luci-milo.cfg`][luci-milo.cfg]:
         *   Use the appropriate definition for the type of the bot being added,
             for example, `ci.gpu_fyi_thin_tester()` should be used for all CI
             tester bots on GPU FYI waterfall.
         *   Make sure to set `triggered_by` property to the builder which
             triggers the testers (like `'GPU Win FYI Builder'`).
-    1. Updates [`chromium.gpu.star`][chromium.gpu.star] or
-       [`chromium.gpu.fyi.star`][chromium.gpu.fyi.star] and their related
-       generated file [`luci-milo.cfg`][luci-milo.cfg]:
-        *   Add new `luci.console_view_entry()` definitions for your new
-            testers (Release and Debug) on the
-            [`chromium.gpu.fyi`][chromium.gpu.fyi] console. Look at the
-            short names and categories and try to come up with a reasonable
-            organization.
+        *   Include a `ci.console_view_entry` for the builder's
+            `console_view_entry` argument. Look at the short names and
+            categories to try and come up with a reasonable organization.
     1.  Run `main.star` in [`src/infra/config`][src/infra/config] to update the
         generated files. Double-check your work there.
     1.  If you were adding a new builder, you would need to also add the new
@@ -487,7 +483,7 @@ Builder].
 
 [How to add a new manually-triggered trybot]: https://chromium.googlesource.com/chromium/src/+/master/docs/gpu/gpu_testing_bot_details.md#How-to-add-a-new-manually_triggered-trybot
 
-[ci.star]:               https://chromium.googlesource.com/chromium/src/+/master/infra/config/buckets/ci.star
+[ci.star]:               https://chromium.googlesource.com/chromium/src/+/master/infra/config/subprojects/ci.star
 [chromium.gpu.star]:     https://chromium.googlesource.com/chromium/src/+/master/infra/config/consoles/chromium.gpu.star
 [chromium.gpu.fyi.star]: https://chromium.googlesource.com/chromium/src/+/master/infra/config/consoles/chromium.gpu.fyi.star
 [cr-buildbucket.cfg]:    https://chromium.googlesource.com/chromium/src/+/master/infra/config/generated/cr-buildbucket.cfg
@@ -542,21 +538,14 @@ trybot for the Win7 NVIDIA GPUs in Release mode. We will call the new bot
     [How to set up new virtual machine instances](#How-to-set-up-new-virtual-machine-instances),
     following the "Manually-triggered GPU trybots" instructions.
 
-1.  Create a CL in the Chromium workspace which does the following. Here's an
-    [outdated example CL](https://chromium-review.googlesource.com/c/chromium/src/+/1974575)
-    and a [reference CL](https://chromium-review.googlesource.com/c/chromium/src/+/2015548)
+1.  Create a CL in the Chromium workspace which does the following. Here's a
+    [reference CL](https://chromium-review.googlesource.com/c/chromium/src/+/2191276)
     exemplifying the new "GCE pool per GPU hardware pool" way.
     1.  Updates [`gpu.try.star`][gpu.try.star] and its related generated file
         [`cr-buildbucket.cfg`][cr-buildbucket.cfg]:
         *   Add the new trybot with the right `builder` define and VMs pool.
             For `gpu-fyi-try-win7-nvidia-rel-64` this would be
             `gpu_win_builder()` and `luci.chromium.gpu.win7.nvidia.try`.
-    1.  Updates the LUCI consoles you want the trybot to show in and their
-        related generated file [`luci-milo.cfg`][luci-milo.cfg]:
-        *   For `gpu-fyi-try-win7-nvidia-rel-64` these would be
-            [`luci.chromium.try.star`][luci.chromium.try.star] and
-            [`tryserver.chromium.win.star`][tryserver.chromium.win.star]
-            consoles. Just add `try/` followed by trybot name to the lists.
     1.  Run `main.star` in [`src/infra/config`][src/infra/config] to update the
         generated files. Double-check your work there.
     1.  Adds the new trybot to [`src/tools/mb/mb_config.pyl`][mb_config.pyl]
@@ -597,7 +586,7 @@ should be possible to send a CL to it.
 mentioned at the bottom of the "Choose tryjobs" pop-up. Contact the
 chrome-infra team if this doesn't work as expected.)
 
-[gpu.try.star]:                https://chromium.googlesource.com/chromium/src/+/master/infra/config/buckets/gpu.try.star
+[gpu.try.star]:                https://chromium.googlesource.com/chromium/src/+/master/infra/config/subprojects/gpu.try.star
 [luci.chromium.try.star]:      https://chromium.googlesource.com/chromium/src/+/master/infra/config/consoles/luci.chromium.try.star
 [tryserver.chromium.win.star]: https://chromium.googlesource.com/chromium/src/+/master/infra/config/consoles/tryserver.chromium.win.star
 
@@ -662,7 +651,7 @@ Win10 Release (CoolNewGPUType)".
     using Choose Trybots in Gerrit.
 
 [scheduler-noop-jobs.star]: https://chromium.googlesource.com/chromium/src/+/master/infra/config/generators/scheduler-noop-jobs.star
-[try.star]:                 https://chromium.googlesource.com/chromium/src/+/master/infra/config/buckets/try.star
+[try.star]:                 https://chromium.googlesource.com/chromium/src/+/master/infra/config/subprojects/try.star
 
 
 ### How to test and deploy a driver and/or OS update
diff --git a/chromium/docs/how_to_add_your_feature_flag.md b/chromium/docs/how_to_add_your_feature_flag.md
index 9888ced5561..d7d6caeaca7 100644
--- a/chromium/docs/how_to_add_your_feature_flag.md
+++ b/chromium/docs/how_to_add_your_feature_flag.md
@@ -14,7 +14,7 @@ For example, if you want to use the flag in src/content, you should add a base::
 If you want to use the flag in blink, you should also read
 [Runtime Enable Features](https://www.chromium.org/blink/runtime-enabled-features).
 
-You can refer to [this CL](https://chromium-review.googlesource.com/c/554510/) and [this document](https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/InitializeBlinkFeatures.md)
+You can refer to [this CL](https://chromium-review.googlesource.com/c/554510/) and [this document](initialize_blink_features.md)
 to see
 
 1. where to add the base::Feature
diff --git a/chromium/docs/ios/build_instructions.md b/chromium/docs/ios/build_instructions.md
index 4fb5b123348..5695097a072 100644
--- a/chromium/docs/ios/build_instructions.md
+++ b/chromium/docs/ios/build_instructions.md
@@ -76,6 +76,8 @@ build directories under `out` for Release and Debug device and simulator
 builds, and generates an appropriate Xcode workspace
 (`out/build/all.xcworkspace`) as well.
 
+More information about [developing with Xcode](xcode_tips.md).
+
 You can customize the build by editing the file `$HOME/.setup-gn` (create it if
 it does not exist).  Look at `src/ios/build/tools/setup-gn.config` for
 available configuration options.
@@ -91,9 +93,11 @@ $ autoninja -C out/Debug-iphonesimulator gn_all
 (`autoninja` is a wrapper that automatically provides optimal values for the
 arguments passed to `ninja`.)
 
-Note: you need to run `setup-gn.py` script every time one of the `BUILD.gn`
-file is updated (either by you or after rebasing). If you forget to run it,
-the list of targets and files in the Xcode solution may be stale.
+Note: The `setup-gn.py` script needs to run every time one of the `BUILD.gn`
+files is updated (either by you or after rebasing). If you forget to run it,
+the list of targets and files in the Xcode solution may be stale. You can run
+the script directly or use either `gclient sync` or `gclient runhooks` which
+will run `setup-gn.py` for you as part of the update hooks.
 
 You can also follow the manual instructions on the
 [Mac page](../mac_build_instructions.md), but make sure you set the
@@ -206,7 +210,7 @@ then it will be impossible to install the application on a device (Xcode will
 display an error stating that "The application was signed with invalid
 entitlements").
 
-## Running apps from the commandline
+## Running apps from the command line
 
 Any target that is built and runs on the bots (see [below](#Troubleshooting))
 should run successfully in a local build. To run in the simulator from the
@@ -285,6 +289,11 @@ hooks as needed.
 
 ## Tips, tricks, and troubleshooting
 
+Remember that the XCode project you interact with while working on Chromium is a
+build artifact, generated from the `BUILD.gn` files. Do not use it to add new
+files; instead see the procedures for [working with
+files](working_with_files.md).
+
 If you have problems building, join us in `#chromium` on `irc.freenode.net` and
 ask there. As mentioned above, be sure that the
 [waterfall](https://build.chromium.org/buildbot/waterfall/) is green and the tree
diff --git a/chromium/docs/ios/working_with_files.md b/chromium/docs/ios/working_with_files.md
new file mode 100644
index 00000000000..37a74a8f417
--- /dev/null
+++ b/chromium/docs/ios/working_with_files.md
@@ -0,0 +1,223 @@
+# Working With Files
+
+Adding, removing, and renaming files in iOS Chromium needs to follow a specific
+procedure that will be unfamiliar to engineers coming from other iOS projects.
+Conceptually, every file is recorded in _four_ locations: the local filesystem,
+git, the `BUILD.gn` files, and the XCode projects. Of these, the XCode project
+is wholly generated from the others.
+
+[TOC]
+
+## Overview
+
+**Do not use XCode to manipulate files.** The XCode project used for iOS
+Chromium is _generated_; it's functionally a build artifact. The various
+`BUILD.gn` files in Chromium define structure of the XCode project file. Running
+`gclient runhooks` causes the project files to be regenerated.
+
+Individual files can have their contents edited within XCode, and all of the
+regular testing and debugging activities can be done within XCode. It just can't
+be used to create files, rename files, delete files, or manipulate the project
+group structure in any way. To do these things, follow the procedures below.
+
+## Adding files
+
+To add any files (new headers, `.mm` or `.cc` implementation files, asset files
+of any kind), the following general steps need to happen:
+
+1.  The file needs to exist in the correct directory of the file system for your
+    Chromium checkout. New files need to be created, or assets need to be
+    copied to the right location.
+
+1.  The new files need to be added to git.
+
+1.  The new files need to be added to a target in a `BUILD.gn` file (usually in
+    the same directory as the newly added file).
+
+1.  The XCode project needs to be regenerated.
+
+For adding new header or implementation files, the following procedure is
+recommended:
+
+1.  Generate the new files using `tools/boilerplate.py`. This will generate the
+    correct header guard macros and include the copyright boilerplate.
+
+2.  Add the newly created files using `git add`.
+
+3.  Edit the `BUILD.gn` file for the directory where the files were added. For
+    each file, add it to the `sources` list for the correct `source_set` in the
+    `BUILD.gn` file. Note that `gn format` (which is run as part of `git cl
+    format`) will take care of alphabetizing the lists along with other
+    formatting, so there's no need to manually do these things. (`BUILD.gn`
+    files cand be edited directly in XCode, or in another editor such as `vi`).
+
+4.  Once all of the files have been created, `add`ed and all `BUILD.gn` files
+    have been updated, run `gclient runhooks` to regenerate all XCode projects.
+
+5.  If XCode is open, it may prompt to "Autocreate Schemes". If so, click on the
+    highlighted "Automatically Create Schemes" button.
+
+In the shell, this procedure would look like this:
+```bash
+// Step 1 -- generate new files.
+$ tools/boilerplate.py ios/chrome/browser/some_feature/feature_class.h
+$ tools/boilerplate.py ios/chrome/browser/some_feature/feature_class.mm
+$ tools/boilerplate.py ios/chrome/browser/some_feature/feature_class_unittest.mm
+// Step 2 -- add the new files.
+$ git add ios/chrome/browser/some_feature/feature_class*
+// Step 3 -- edit the BUILD.gn file in the editor of your choice
+$ vi ios/chrome/browser/some_feature/BUILD.gn
+// Step 4 -- regenerate the XCode Projects
+$ gclient runhooks
+```
+
+To add asset files, follow this procedure:
+
+1.  Copy the asset files to the correct directory, with the correct names
+    (including `@2x` and `@3x` suffixes) Note that images are stored in
+    `.imageset` directories, conventionally inside `resources` directories for a
+    given UI feature. New directories, if needed, are created in the usual way
+    (`mkdir`). Note that there is no equivalent of `boilerplate.py` for images
+    or other asset files.
+
+1.  Create or copy `Contents.json` files for each new `.imageset` directory,
+    with the appropriate contents.
+
+1.  Add all image and `Contents.json` files using `git add`.
+
+1.  Edit the `BUILD.gn` file in the containing `resources` directory, adding
+    `imageset` entries for each added `.imageset` directory, and then grouping
+    all assets into a new or existing `group()` declaration with a `public_deps`
+    list containing all of the `imageset` targets.
+
+1.  Regenerate the XCode project with `gclient runhooks`.
+
+To add Markdown documentation files, the procedure is much simpler. These files
+are automatically added to the XCode project without `BUILD.gn` entries, and
+they have no required boilerplate. So adding new docs is as simple as:
+
+1.  Create a new `.md` file in the appropriate directory (`docs/ios`, for
+    example).
+
+1. `git add` the file.
+
+The newly added file will be visible in XCode after the next `gclient runhooks`.
+
+## Moving and renaming files.
+
+Renaming a file involves updating the filename in all of the places where it
+exists: the file names in the filesystem, the file names in git, header guards
+in files, import declarations in files, listings in BUILD.gn files, and
+internally in the XCode project. As with adding a file, different tools are used
+for each of these. Unlike creating a file, which starts with actually adding a
+file to the filesystem, a rename starts with updating git (via `git mv`), then
+using the `mass_rename` tool to update file contents.
+
+`tools/git/mass_rename.py` works by looking at _uncommitted_ file moves in git,
+and then updating all includes, header guards, and BUILD.gn entries to use the
+new name. It doesn't update some other files, such as `Contents.json` files for
+image assets. It also doesn't change any symbols in code, so class and variable
+names won't be changed.
+
+For many file moves, it will be simpler to use another tool,
+`tools/git/move_source_file.py`, which combines `git mv` and `mass_rename` in a
+single action. For example, renaming `feature_class` to `renamed_class` would be
+done like this:
+```bash
+    $ tools/git/move_source_file.py ios/chrome/browser/some_feature/feature_class.h \
+        ios/chrome/browser/some_feature/renamed_class.h
+    $ tools/git/move_source_file.py ios/chrome/browser/some_feature/feature_class.mm \
+        ios/chrome/browser/some_feature/renamed_class.mm
+```
+
+The step-by-step procedure for a rename is:
+
+1.  If there are other uncommitted changes before the move, it's usually
+    cleanest to commit before starting the move.
+
+1.  `move_source_file` each file that needs to be renamed. This renames the file
+    in both the file system and in git, and in most places where it's used in
+    code.
+
+1.  Run `gclient runhooks` to update the XCode project. Check that all of the
+    needed name changes have been made (for example, by building all targets).
+    Make any other needed fixes.
+
+1.  If any classes or other symbols need to be renamed (remember that the name
+    of the primary interface in each file must match the file name), make those
+    changes. Find-and-replace tools like `tools/git/mffr.py` or XCode's
+    Find/Replace can help here, but there are no compiler-aware tools that can
+    do a "smart" rename.
+
+1.  Commit all changes (`git commit -a -m <your comment>`).
+
+A move—where a file is moved to a different directory—is in most respects
+performed using the same steps as a rename. However, while `mass_rename.py` (and
+thus `move_source_file.py`) will update existing file names in `BUILD.gn` files,
+it won't move entries from one `BUILD.gn` file to another. To move files to a
+different directory, the preceding procedure is used, but between steps 2 and 3
+(after moving the files, but before regenerating the XCode project), the old
+filenames will need to be removed from the `BUILD.gn` files in the old
+directories and added to the `BUILD.gn` files in the new directories.
+
+Also note that while `move_source_file` must be used separately for each file
+being renamed within a directory, it (just like `git mv`) can move multiple
+files without renaming to a new directory in a single command:
+
+```bash
+$ tools/git/mass_rename.py ios/chrome/browser/some_feature/feature_class.* \
+    ios/chrome/browser/some_feature/feature_class_unittest.mm \
+    ios/chrome/browser/other_feature/
+```
+
+## Deleting files.
+
+Deleting files follows the same patterns as adding and moving files. As with a
+file move, it's best to begin with deleting the files from git.
+
+Typically, before actually removing a file, first all usage of the interface(s)
+in the file(s) will be removed, and the file will no longer be `#imported`
+anywhere.
+
+Step-by step:
+
+1.  `git rm` the files you want to remove. This will also remove the files
+    from the filesystem.
+
+1.  Manually remove the `BUILD.gn` entries for the files.
+
+1.  Regenerate the XCode project (with `gclient runhooks`) to remove the files
+    from XCode.
+
+## Finally.
+
+It's easy to miss some uses of a file that was renamed or deleted, and fixing
+compilation errors discovered in the commit queue means another
+commit-upload-dry run cycle (at least). To minimize this, after any change that
+adds, renames, moves, or deletes files, be sure to take the following steps:
+
+1.  `git cl format` to update the formatting of all files.
+
+1.  `gn check` to make sure that any new or moved files follow the dependency
+    rules (for example: `gn check -C out/Debug-iphonesimulator/`).
+
+1.  Build all targets, to make sure that everything has been added, changed, or
+    removed correctly. This can be done by selecting the "All" target in XCode
+    and building (`⌘-B`), or from the command line (for example, `autoninja -C
+    out/Debug-iphonesimulator/`).
+
+Changes that involve adding or deleting more than a few files, and most renames
+of any size, should be in a single CL with no other changes, for ease of
+reviewing and (if necessary) reverting or cherry-picking.
+
+## Recovering from accidental XCode Project usage.
+
+If files are accidentally added, renamed, or moved through XCode, other settings
+in the XCode project may be changed that will introduce strange local build
+failures. In this case, take the following steps to recover.
+
+1. Quit XCode.
+
+1. Delete all generated XCode projects and associated files: `rm -rf out/build`.
+
+1. Regenerate all XCode projects: `gclient runhooks`.
diff --git a/chromium/docs/ios/xcode_tips.md b/chromium/docs/ios/xcode_tips.md
new file mode 100644
index 00000000000..0e643693dce
--- /dev/null
+++ b/chromium/docs/ios/xcode_tips.md
@@ -0,0 +1,58 @@
+# Developing Chrome for iOS with the Xcode IDE
+
+This document contains notes used during a presentation about how to use Xcode
+to develop Chrome for iOS.
+
+## Background
+
+### .xcworkspace and .xcproject
+
+*   Generated from BUILD.gn files.
+*   Don't make changes to it as it is a "fake" representation of the project
+    -   changes will not be committed
+    -   changes will be overwritten without warning
+*   Modify BUILD files instead
+*   Added BUILD.gn files/`source_sets` need to be referenced from other ones as
+    a `dep` in order for it to be shown in xcode.
+
+### Adding new files
+
+*   Create new files with `tools/boilerplate.py`
+*   Add files to BUILD.gn `mate ios/chrome/...BUILD.gn`
+*   Add new source_set target as a dep of another target
+*   Execute `gclient runhooks` or `gclient sync`
+
+### Simulators
+
+*   Simulators build for Mac architecture, not emulators. Fast, generally good
+    for most development
+*   To run on device, need provisioning profiles and certificate
+
+## Xcode
+
+*   Project location is `src/out/build/`, open `all.workspace`
+*   Choose "Automatically generate targets" after a `gclient sync`
+*   Start typing while dropdowns are presented to filter the displayed items
+
+### Targets
+
+*   `chrome' is the main application target
+*   `ios_web_shell` and `ios_web_view_shell` test lower level of application
+
+### Tests
+
+*   Unittests/Inttests
+    -   Add flags to specify tests to run (Option-Click on unittest target name,
+        select Run from left panel, add to "Arguments Passed on Launch")
+    -   `gtest_filter=TestClass.*`
+    -   `gtest_repeat=20`
+    -   Full list of options available by sending an unknown option
+
+*   EarlGrey
+    -   EG1 deprecated
+    -   EG2 are current UI tests
+        -   A separate "test" process communicates with "the app".
+        -   EDO is term for "distant object" on "the other side".
+        -   egtest files can run under both EG1 and EG2 with correct setup in
+            BUILD.gn because the layer of helpers encapsulate the necessary
+            differences.
diff --git a/chromium/docs/linux/build_instructions.md b/chromium/docs/linux/build_instructions.md
index 23815498823..2f28db7117d 100644
--- a/chromium/docs/linux/build_instructions.md
+++ b/chromium/docs/linux/build_instructions.md
@@ -145,7 +145,7 @@ could use `Goma`.
 If you are not a Googler and would like to use `Goma`
 [sign up](https://docs.google.com/forms/d/1NKHcyqYqw3c4jftrLPwvyiPlolRm4Hf6ObrB83wHXy8/viewform).
 
-Once you've allowed to use `Goma` service and installed the client,
+Once you're allowed to use `Goma` and have installed the client,
 [set the following GN args](https://www.chromium.org/developers/gn-build-configuration#TOC-Goma):
 
 ```
@@ -183,7 +183,6 @@ it. e.g. Intel, Opera, Samsung (this is not useful if you're using Goma).
 In order to use `icecc`, set the following GN args:
 
 ```
-linux_use_bundled_binutils=false
 use_debug_fission=false
 is_clang=false
 ```
diff --git a/chromium/docs/linux/debugging.md b/chromium/docs/linux/debugging.md
index 1310a454e69..fd96694d8ca 100644
--- a/chromium/docs/linux/debugging.md
+++ b/chromium/docs/linux/debugging.md
@@ -258,6 +258,10 @@ can also step or execute backwards. This works by first recording a trace
 and then debugging based on that. I recommend installing it by compiling
 [from source](https://github.com/mozilla/rr/wiki/Building-And-Installing).
 
+Currently you must apply a patch adding
+[support for recording the MADV_WIPEONFORK](https://bugs.chromium.org/p/chromium/issues/detail?id=1082304#c6)
+syscall as upstream rr triggers an internal assert on this call.
+
 Once installed, you can use it like this:
 ```
 rr record out/Debug/content_shell --single-process --no-sandbox --disable-hang-monitor --single-process  --disable-seccomp-sandbox --disable-setuid-sandbox
@@ -272,6 +276,25 @@ rr replay
 (gdb) reverse-fin # run to where this function was called from
 ```
 
+You can debug multi-process chrome using `rr -f [PID]`. To find the process
+id you can either run `rr ps` after recording, or a convenient way
+to find the correct process id is to run with `--vmodule=render_frame_impl=1`
+which will log a message on navigations. e.g.
+
+```
+$ rr record out/Debug/content_shell --disable-hang-monitor --no-sandbox --disable-seccomp-sandbox --disable-setuid-sandbox --vmodule=render_frame_impl=1 https://google.com/
+rr: Saving execution to trace directory `...'.
+...
+[128515:128515:0320/164124.768687:VERBOSE1:render_frame_impl.cc(4244)] Committed provisional load: https://www.google.com/
+```
+
+From the log message we can see that the site was loaded into process 128515
+and can set a breakpoint for when that process is forked.
+
+```
+rr replay -f 128515
+```
+
 ### Graphical Debugging Aid for Chromium Views
 
 The following link describes a tool that can be used on Linux, Windows and Mac under GDB.
diff --git a/chromium/docs/lldbinit.md b/chromium/docs/lldbinit.md
index 7dc4e7e20b3..ee88aada8be 100644
--- a/chromium/docs/lldbinit.md
+++ b/chromium/docs/lldbinit.md
@@ -11,3 +11,23 @@ To use, add the following to your `~/.lldbinit`
 script sys.path[:0] = ['<.../path/to/chromium/src/tools/lldb>']
 script import lldbinit
 ```
+
+## How to attach to a process with lldb and start debugging
+
+- Follow the instructions above to create your `~/.lldbinit` file, don't forget to put the correct path to Chromium source in there.
+- Inside of your Chromium checkout, run `lldb out/Default/chrome` (or `out/Debug/chrome`)
+    - On Mac, most likely, `lldb out/Default/Chromium.app/Contents/MacOS/Chromium`
+- Keep lldb running and start Chromium separately with `--no-sandbox` flag:
+    - On Linux, `out/Default/chrome --no-sandbox`
+    - On Mac, `out/Default/Chromium.app/Contents/MacOS/Chromium --no-sandbox`
+    - Note: if you start the process from lldb using `process launch -- --no-sandbox`, you will attach to the main browser process and will not be able to debug tab processes.
+- In Chromium, go to Customize and Control Chromium (three dots) -> More Tools -> Task Manager
+- Depending on what tab or process you want to debug, note the process ID.
+- In the lldb shell:
+    - Execute `process attach -p PID`. PID is the process ID of the tab (process) you want to debug.
+        - Note: it might take a while. Once lldb attaches to the process, you will see a message `Process PID stopped` and some stack traces.
+    - Now you can set breakpoints, for example, `breakpoint set -f inspector_overlay_agent.cc -l 627`.
+    - Execute `cont` to continue the execution of the process.
+    - Perform the actions which would trigger the breakpoint. lldb will stop the execution for you to inspect.
+    - You can pause the execution at any time by pressing Ctrl + C.
+    - Type `help` to learn more about different lldb commands.
diff --git a/chromium/docs/login/first_user_run_oobe.md b/chromium/docs/login/first_user_run_oobe.md
index be8a594c0d8..9a41f051143 100644
--- a/chromium/docs/login/first_user_run_oobe.md
+++ b/chromium/docs/login/first_user_run_oobe.md
@@ -94,9 +94,8 @@ enrollment, if they wish.
 The final step of the opt-in flow is informing the user the Assistant is ready,
 and offering to enable some advanced features, if any are available.
 
-Much of this flow is managed by assistant::mojom::AssistantSettingsManager
-service. To effectively test the screen flow, this service should be faked by
-the test.
+Much of this flow is managed by chromeos::assistant::AssistantSettings service.
+To effectively test the screen flow, this service should be faked by the test.
 
 # Multi-device Setup screen
 
diff --git a/chromium/docs/mac/icons.md b/chromium/docs/mac/icons.md
index effb28ee7bf..b7619217637 100644
--- a/chromium/docs/mac/icons.md
+++ b/chromium/docs/mac/icons.md
@@ -26,14 +26,9 @@ scrambling of the icons in display. If the old types work, why mess with them?
 
 ## Source PNG files
 
-Use whatever tools you want to create the PNG files, but please note the
-following:
-
-1. The PNG files must be in full RGB mode (i.e. not indexed-color). This will be
-enforced by the `png_check.py` tool below.
-1. The dimensions of the images in the PNG files must match exactly the size
-indicated by their filename. This will be enforced by the `makeicns2` tool
-below.
+Use whatever tools you want to create the PNG files, but please note that the
+dimensions of the images in the PNG files must match exactly the size indicated
+by their filename. This will be enforced by the `makeicns2` tool below.
 
 ## Construction
 
diff --git a/chromium/docs/media/media_pipeline_overview.png b/chromium/docs/media/media_pipeline_overview.png
new file mode 100644
index 00000000000..da367116b28
--- /dev/null
+++ b/chromium/docs/media/media_pipeline_overview.png
diff --git a/chromium/docs/mojo_and_services.md b/chromium/docs/mojo_and_services.md
index 8ff938d0a2f..2aff980269f 100644
--- a/chromium/docs/mojo_and_services.md
+++ b/chromium/docs/mojo_and_services.md
@@ -218,7 +218,7 @@ void RenderFrameHostImpl::GetPingResponder(
 
 // browser_interface_binders.cc
 void PopulateFrameBinders(RenderFrameHostImpl* host,
-                          service_manager::BinderMap* map) {
+                          mojo::BinderMap* map) {
 ...
   // Register the handler for PingResponder.
   map->Add<example::mojom::PingResponder>(base::BindRepeating(
@@ -447,7 +447,7 @@ which maps specific interfaces to their handlers in respective hosts:
 ``` cpp
 // //content/browser/browser_interface_binders.cc
 void PopulateFrameBinders(RenderFrameHostImpl* host,
-                          service_manager::BinderMap* map) {
+                          mojo::BinderMap* map) {
 ...
   map->Add<magic::mojom::GoatTeleporter>(base::BindRepeating(
       &RenderFrameHostImpl::GetGoatTeleporter, base::Unretained(host)));
diff --git a/chromium/docs/parsing_test_results.md b/chromium/docs/parsing_test_results.md
index b87ce80c1e6..7431ac6502f 100644
--- a/chromium/docs/parsing_test_results.md
+++ b/chromium/docs/parsing_test_results.md
@@ -17,8 +17,8 @@ of the configuration. Some examples:
 
 * *android_compile_dbg* is a compile-only [no tests] build of Chromium for
   Android, using the *debug* configuration.
-* *android-kitkat-arm-rel* builds and runs tests for Chromium for Android,
-  using the *release* configuration on a kitkat device.
+* *android-lollipop-arm-rel* builds and runs tests for Chromium for Android,
+  using the *release* configuration on a lollipop device.
 * *win7-rel* builds and runs tests for Chromium on Windows, using
   the release configuration on a Windows 7 device. *ng* stands for next
   generation, but this has no meaning as the previous generation was already
diff --git a/chromium/docs/patterns/synchronous-runloop.md b/chromium/docs/patterns/synchronous-runloop.md
new file mode 100644
index 00000000000..bb6c187fd6e
--- /dev/null
+++ b/chromium/docs/patterns/synchronous-runloop.md
@@ -0,0 +1,345 @@
+# The Synchronous RunLoop Pattern
+
+The synchronous RunLoop pattern involves creating a new RunLoop, setting up a
+specified quit condition for it, then calling Run() on it to block the current
+thread until that quit condition is reached.
+
+## Use this pattern when:
+
+You need to **block the current thread** until an event happens, and you have a
+way to get notified of that event, via a callback or observer interface or
+similar. A couple of common scenarios might be:
+
+* Waiting for an asynchronous event (like a network request) to complete
+* Waiting for an animation to finish
+* Waiting for a page to have loaded
+* Waiting for some call that requires a thread hop to complete
+
+The fact that this blocks a thread means it is **almost never appropriate
+outside test code**.
+
+## Don't use this pattern when:
+
+* You don't really need the entire thread to wait
+* You don't have and can't add a way to get notified when the event happens
+* You're waiting for a timer to fire - for that, [TaskEnvironment] is likely a
+  better fit.
+
+## Alternatives / see also:
+
+* [TaskEnvironment]
+* Restructuring your code to not require blocking a thread
+
+## How this pattern works:
+
+This pattern relies on two important facts about [base::RunLoop]:
+
+1. `base::RunLoop::Quit()` is idempotent - once a RunLoop enters the quit
+   state, quitting it again does nothing
+2. Once a RunLoop is in the quit state, calling `base::RunLoop::Run()` on it is
+   a no-op
+
+That means that if your code does this:
+
+```c++
+  base::RunLoop loop;
+  maybe-asynchronously { loop.Quit(); }
+  loop.Run();
+  LOG(INFO) << "Hello!";
+```
+
+then regardless of whether the maybe-asynchronous `loop.Quit()` is executed
+before or after `loop.Run()`,  the "Hello!" message will never be printed before
+both `loop.Run()` and `loop.Quit()` have happened. If the `Quit` happens
+before the `Run`, the `Run` will be a no-op; if the `Quit` happens after the
+`Run` has started, the `Run` will exit after the `Quit`.
+
+## How to use this pattern in Chromium:
+
+If the asynchronous thing in question takes a completion callback:
+
+```c++
+  base::RunLoop run_loop;
+  Reply reply;
+  DoThingAndReply(
+      base::BindLambdaForTesting([&](const Reply& r) {
+          reply = r;
+          run_loop.Quit();
+      }));
+  run_loop.Run();
+```
+
+or perhaps even just:
+
+```c++
+  base::RunLoop run_loop;
+  DoThing(run_loop.QuitClosure());
+  run_loop.Run();
+```
+
+If there exists a GizmoObserver interface with an OnThingDone event:
+
+```c++
+  class TestGizmoObserver : public GizmoObserver {
+   public:
+    TestGizmoObserver(base::RunLoop* loop, Gizmo* thing)
+        : GizmoObserver(thing), loop_(loop) {}
+
+    // GizmoObserver:
+    void OnThingStarted(Gizmo* observed_gizmo) override { ... }
+    void OnThingProgressed(Gizmo* observed_gizmo) override { ... }
+    void OnThingDone(Gizmo* observed_gizmo) override {
+      loop_->Quit();
+    }
+  };
+
+  base::RunLoop run_loop;
+  TestGizmoObserver observer(&run_loop, gizmo);
+  gizmo->StartDoingThing();
+  run_loop.Run();
+```
+
+This is sometimes wrapped up into a helper class that internally constructs the
+RunLoop like so, if all you need to do is wait for the event but don't care
+about observing any intermediate states too:
+
+```c++
+  class ThingDoneWaiter : public GizmoObserver {
+   public:
+    ThingDoneWaiter(Gizmo* thing) : GizmoObserver(thing) {}
+
+    void Wait() {
+      run_loop_.Run();
+    }
+
+    // GizmoObserver:
+    void OnThingDone(Gizmo* observed_gizmo) {
+      run_loop_.Quit();
+    }
+
+   private:
+    RunLoop run_loop_;
+  };
+
+  ThingDoneWaiter waiter(gizmo);
+  gizmo->StartDoingThing();
+  waiter.Wait();
+```
+
+## Events vs States
+
+It's important to differentiate between waiting on an *event* (such as a
+notification or callback being fired) vs waiting for a *state* (such as a
+property on a given object).
+
+When waiting for events, it is crucial that the observer is constructed in time
+to see the event (see also [waiting to late](#starting-waiting-too-late)).
+States, on the other hand, can be queried beforehand in the body of a
+Wait()-style function.
+
+The following is an example of a Waiter helper class that waits for a state, as
+opposed to an event:
+
+```c++
+  class GizmoReadyWaiter : public GizmoObserver {
+   public:
+    GizmoReadyObserver(Gizmo* gizmo)
+        : gizmo_(gizmo) {}
+    ~GizmoReadyObserver() override = default;
+
+    void WaitForGizmoReady() {
+      if (!gizmo_->ready()) {
+        gizmo_observer_.Add(gizmo_);
+        run_loop_.Run();
+      }
+    }
+
+    // GizmoObserver:
+    void OnGizmoReady(Gizmo* observed_gizmo) {
+      run_loop_.Quit();
+    }
+
+   private:
+    RunLoop run_loop_;
+    Gizmo* gizmo_;
+    ScopedObserver<Gizmo, GizmoObserver> gizmo_observer_{this};
+  };
+```
+
+## Sharp edges
+
+### Starting to wait for an event too late
+
+A common mis-use of this pattern is like so:
+
+```c++
+  gizmo->StartDoingThing();
+  base::RunLoop run_loop;
+  TestGizmoObserver observer(&run_loop, gizmo);
+  run_loop.Run();
+```
+
+This looks tempting because it seems that you can write a helper function:
+
+```c++
+  void TerribleHorribleNoGoodVeryBadWaitForThing(Gizmo* gizmo) {
+    base::RunLoop run_loop;
+    TestGizmoObserver observer(&run_loop, gizmo);
+    run_loop.Run();
+  }
+```
+
+and then your test code can simply read:
+
+```c++
+  gizmo->StartDoingThing();
+  TerribleHorribleNoGoodVeryBadWaitForThing(gizmo);
+```
+
+However, this is a recipe for a flaky test: if `gizmo->StartDoingThing()`
+*completes* and would deliver the `OnThingDone` callback before your
+`TestGizmoObserver` is ever constructed, the `TestGizmoObserver` will never
+receive `OnThingDone`, and then your `run_loop.Run()` will run forever,
+frustrating a future tree sheriff (and then probably you, shortly afterward).
+This is especially dangerous when `gizmo->StartDoingThing()` involves a thread
+hop or network request, because these can unpredictably complete before or after
+your observer gets constructed. To be safe, always begin observing the event
+*before* running the code that will eventually cause the event!
+
+If you still really want a helper function, perhaps you just want to inline the
+start:
+
+```c++
+  void NiceFriendlyDoThingAndWait(Gizmo* gizmo) {
+    base::RunLoop run_loop;
+    TestGizmoObserver observer(&run_loop, gizmo);
+    gizmo->StartDoingThing();
+    run_loop.Run();
+  }
+```
+
+with the test code being:
+
+```c++
+  NiceFriendlyDoThingAndWait(gizmo);
+```
+
+Note that this is not an issue when waiting on a *state*, since the observer can
+query to see if that state is already the current state.
+
+### Guessing RunLoop cycles
+
+Sometimes, there's no easy way to observe completion of an event. In that case,
+if the code under test looks like this:
+
+```c++
+  void StartDoingThing() { PostTask(&StepOne); }
+  void StepOne() { PostTask(&StepTwo); }
+  void StepTwo() { /* done! */ }
+```
+
+it can be tempting to do:
+
+```c++
+  gizmo->StartDoingThing();
+  base::RunLoop().RunUntilIdle();
+  /* now it's done! */
+```
+
+However, doing this is adding dependencies to your test code on the exact async
+behavior of the production code - for example, the production code may depend on
+work happening on another TaskRunner, which this won't successfully wait for.
+This will make your test brittle and flaky.
+
+Instead of doing this, it's vastly better to add a way (even if it's just via a
+[test API]) to observe the event you're interested in.
+
+### Not managing lifetimes
+
+As with most patterns, lifetimes can be an issue with this pattern when using
+observers. If you are waiting on a given event to happen, and the object that's
+being observed instead goes out of scope, the test may hang.
+Similar badness can happen if the Waiter isn't properly removed as an observer,
+which could lead to Use-After-Frees.
+
+There are two good mitigation practices here.
+
+#### Keep Waiter-style helper classes as narrowly scoped as possible.
+Consider something like
+```c++
+TEST_F(GizmoTest, WaitForGizmo) {
+  GizmoWaiter waiter;
+  Gizmo gizmo;
+  gizmo.Initialize();
+  waiter.WaitForGizmoReady();
+  ASSERT_TRUE(gizmo.ready());
+}
+```
+
+This looks safe, but may not be. If GizmoObserver removes itself as an observer
+from Gizmo in its destructor, this will result in a Use-After-Free during the
+test tear down.  Instead, scope the GizmoWaiter more narrowly:
+```c++
+TEST_F(GizmoTest, WaitForGizmo) {
+  Gizmo gizmo;
+  {
+    GizmoWaiter waiter;
+    gizmo.Initialize();
+    waiter.WaitForGizmoReady();
+  }
+  ASSERT_TRUE(gizmo.ready());
+}
+```
+
+Since the GizmoWaiter is now narrowly-scoped, it will be destroyed when it is
+no longer needed, and avoid Use-After-Free concerns.
+
+#### If in doubt, handle the destruction case appropriately
+If you need to potentially handle the case where the object being observed is
+destroyed while a waiter is still active, you can handle the destruction case
+gracefully.
+
+
+```c++
+  class GizmoReadyWaiter : public GizmoObserver {
+   public:
+    GizmoReadyObserver(Gizmo* gizmo)
+        : gizmo_(gizmo) {}
+    ~GizmoReadyObserver() override = default;
+
+    void WaitForGizmoReady() {
+      ASSERT_TRUE(gizmo_)
+          << "Trying to call Wait() after the Gizmo was destroyed!";
+      if (!gizmo_->ready()) {
+        gizmo_observer_.Add(gizmo_);
+        run_loop_.Run();
+      }
+    }
+
+    // GizmoObserver:
+    void OnGizmoReady(Gizmo* observed_gizmo) {
+      gizmo_observer_.Remove(observed_gizmo);
+      run_loop_.Quit();
+    }
+    void OnGizmoDestroying(Gizmo* observed_gizmo) {
+      DCHECK_EQ(gizmo_, observed_gizmo);
+      gizmo_ = nullptr;
+      // Remove the observer now, to avoid a UAF in the destructor.
+      gizmo_observer_.Remove(observed_gizmo);
+      // Bail out so we don't time out in the test waiting for a ready state
+      // that will never come.
+      run_loop_.Quit();
+      // Was this a possible expected outcome? If not, consider:
+      // ADD_FAILURE() << "The Gizmo was destroyed before it was ready!";
+    }
+
+   private:
+    RunLoop run_loop_;
+    Gizmo* gizmo_;
+    ScopedObserver<Gizmo, GizmoObserver> gizmo_observer_{this};
+  };
+```
+
+[base::RunLoop]: ../../base/run_loop.h
+[TaskEnvironment]: ../threading_and_tasks_testing.md
+[test API]: testapi.md
diff --git a/chromium/docs/profiling.md b/chromium/docs/profiling.md
index aa0599c5bd4..22508adf107 100644
--- a/chromium/docs/profiling.md
+++ b/chromium/docs/profiling.md
@@ -125,6 +125,54 @@ Open devtools, and in the console, use `chrome.gpuBenchmarking.startProfiling` a
 
     > chrome.gpuBenchmarking.startProfiling('perf.data'); chrome.gpuBenchmarking.smoothScrollBy(1000, () => { chrome.gpuBenchmarking.stopProfiling() });
 
+### Profiling content_shell with callgrind
+
+This section contains instructions on how to do profiling using the callgrind/cachegrind tools provided by valgrind. This is not a sampling profiler, but a profiler based on running on a simulated CPU. The instructions are Linux-centered, but might work on other platforms too.
+
+#### GN configuration
+
+As with the other options you typically profile a release build with symbols. In order to do so, add enable_profiling to `args.gn`:
+
+```
+enable_profiling = true
+```
+
+#### Install valgrind
+
+```
+sudo apt-get install valgrind
+```
+
+#### Profile
+
+Run `content_shell` with callgrind to create a profile. A `callgrind.<pid>` file will be dumped when exiting the browser or stopped with CTRL-C:
+
+```
+valgrind --tool=callgrind content_shell --single-process --no-sandbox <url>
+```
+
+Alternatively use cachegrind which will give you CPU cycles per code line:
+
+```
+valgrind --tool=cachegrind content_shell --single-process --no-sandbox <url>
+```
+
+Using single-process is for simple profiling of the renderer. It should be possible to run in multi-process and attach to a renderer process.
+
+#### Install KCachegrind
+
+Warning: this will install a bunch of KDE dependencies.
+
+```
+sudo apt-get install kcachegrind
+```
+
+#### Explore with KCachegrind
+
+```
+kcachegrind callgrind.<pid>
+```
+
 ## Profiling on Android
 
 Android (Nougat and later) supports profiling using the [simpleperf](https://developer.android.com/ndk/guides/simpleperf) tool.
diff --git a/chromium/docs/render_document.md b/chromium/docs/render_document.md
new file mode 100644
index 00000000000..7cd80461f3c
--- /dev/null
+++ b/chromium/docs/render_document.md
@@ -0,0 +1,64 @@
+# What is RenderDocument?
+
+## TL;DR
+
+Chrome currently switches to a new RenderFrameHost
+when loading a new document
+if the render process is different to the  previous one.
+The RenderDocument project is about making the switch to happen unconditionally.
+This:
+
+* Eliminates the logic for navigating inside the same RenderFrameHost
+* Makes RenderFrameHost in the browser process 1:1 with the Document.
+* Prevents security bugs,
+  e.g. reusing the data/capabilities from the wrong document.
+
+## Details
+
+Previously when we navigate a frame from one page to another,
+the second page may appear in a new RenderFrame
+or we may reuse the existing RenderFrame to load the second page.
+Which happens depends on many things,
+including which site-isolation policy we are following
+and whether the pages are from the same site or not.
+With RenderDocument,
+the second page will always use a new RenderFrame
+(excluding navigation within a document).
+
+Also when reloading a crashed frame
+we reused the browser-side RenderFrameHost.
+With RenderDocument we create a new RenderFrameHost
+for crashed frames.
+
+## Read more
+
+https://crbug.com/936696
+
+[design doc](https://docs.google.com/document/d/1C2VKkFRSc0kdmqjKan1G4NlNlxWZqE4Wam41FNMgnmA)
+
+[high-level view of the work needed](https://docs.google.com/document/d/1UzVOmTj2IJ0ecz7CZicTK6ow2rr9wgLTGfY5hjyLmT4)
+
+[discussion of how we can land it safely](https://docs.google.com/document/d/1ZHWWEYT1L5Zgh2lpC7DHXXZjKcptI877KKOqjqxE2Ns)
+
+# Stages
+
+We have 3 stages that are behind flags.
+
+1. crashed-frames:
+  A new RenderFrameHost is used for reloading a crashed document.
+2. subframes:
+  A new RenderFrameHost is used for every nested document.
+3. main frames:
+  A new RenderFrameHost is used for every document.
+
+# Test changes
+
+## RenderFrameHost reference becomes invalid
+
+Enabling this for subframes and main frames causes many tests to fail.
+It is common for tests to get a reference to a RenderFrameHost
+and then navigate that frame,
+assuming that the reference will remain valid.
+This assumption is no longer valid.
+The test needs to get a reference to the new RenderFrameHost,
+e.g. by traversing the frame tree again.
diff --git a/chromium/docs/security/clusterfuzz-for-sheriffs.md b/chromium/docs/security/clusterfuzz-for-sheriffs.md
new file mode 100644
index 00000000000..7f1c81a5cf6
--- /dev/null
+++ b/chromium/docs/security/clusterfuzz-for-sheriffs.md
@@ -0,0 +1,55 @@
+# Security Sheriff ClusterFuzz instructions
+
+[TOC]
+
+This page has instructions for [Security Sheriffs](sheriff.md) in how best to use
+[ClusterFuzz](https://clusterfuzz.com) to reproduce and label bugs.
+
+## Basics
+
+[https://clusterfuzz.com/upload-testcase](https://clusterfuzz.com/upload-testcase)
+allows you to upload files to reproduce crashes on various platforms and will
+identify revision ranges when the regression was introduced. If a test case
+requires multiple files, they can be uploaded together in a zip or tar
+archive: the main file needs to contain the words `index`, `crash` or `test`.
+
+Please *do* specify the crbug number when uploading the test case. This will allow
+ClusterFuzz to keep the crbug updated with progress.
+
+## Useful jobs
+
+You should chose the right job type depending on the format of file you want to
+test:
+
+* repro.html [linux_asan_chrome_mp](https://clusterfuzz.com/upload-testcase?upload=true&job=linux_asan_chrome_mp)
+  or [windows_asan_chrome](https://clusterfuzz.com/upload-testcase?upload=true&job=windows_asan_chrome)
+* repro.js [linux_asan_d8](https://clusterfuzz.com/upload-testcase?upload=true&job=linux_asan_d8)
+* repro.pdf [libfuzzer_pdfium_asan / pdfium_fuzzer](https://clusterfuzz.com/upload-testcase?upload=true&job=libfuzzer_pdfium_asan&target=pdfium_fuzzer)
+  or [libfuzzer_pdfium_asan / pdfium_xfa_fuzzer](https://clusterfuzz.com/upload-testcase?upload=true&job=libfuzzer_pdfium_asan&target=pdfium_xfa_fuzzer)
+
+## MojoJS
+
+[MojoJS](../../mojo/public/js/README.md) is a means for a renderer process to use
+Mojo IPCs directly from JavaScript. Although it's not enabled in normal production
+Chrome builds, it's a great way to simulate how a compromised renderer can attack
+other processes over IPC.
+
+Because Mojo IPCs change with each version of Chrome, the test case needs to
+use exactly the right MojoJS bindings. MojoJS bugs typically specify to use
+`python ./copy_mojo_bindings.py` to put such bindings in place, but that does not
+work for ClusterFuzz where it will need to bisect across many versions of Chrome
+with many versions of Mojo.
+
+Therefore, do this instead:
+
+* In the PoC, replace all paths where it's loading MojoJS scripts to be prefixed
+  with `file:///gen` instead. For example:
+  ```
+  <script src="file:///gen/mojo/public/js/mojo_bindings_lite.js">
+  ```
+  This works because most of the ClusterFuzz Chrome binaries are [now built with](https://chromium-review.googlesource.com/c/chromium/src/+/1119727) `enable_ipc_fuzzer=true`.
+* If you believe the bug will reproduce on Linux, use the [linux_asan_chrome_mojo](https://clusterfuzz.com/upload-testcase?upload=true&job=linux_asan_chrome_mojo) job type.
+* If you believe the bug will only reproduce on Android, [ClusterFuzz can't help right now](https://crbug.com/1067103).
+* Otherwise, use any job type but specify extra command-line flags `--enable-blink-features=MojoJS`. In this case, ClusterFuzz might declare that a browser process crash is Critical severity, whereas because of the precondition of a compromised renderer [you may wish to adjust it down to High](severity-guidelines.md).
+
+[Example bug where these instructions have worked](https://crbug.com/1072983).
diff --git a/chromium/docs/security/compromised-renderers.md b/chromium/docs/security/compromised-renderers.md
new file mode 100644
index 00000000000..6733e1384e6
--- /dev/null
+++ b/chromium/docs/security/compromised-renderers.md
@@ -0,0 +1,386 @@
+# Threat Model And Defenses Against Compromised Renderers
+
+Given the complexity of the browser, our threat model must use a "defense
+in depth" approach to limit the damage that occurs if an attacker
+finds a way around the Same Origin Policy or other security logic in the
+renderer process.
+For example, the combination of Chrome's sandbox, IPC security checks, and Site
+Isolation limit what an untrustworthy renderer process can do.  They
+protect Chrome users against attackers, even when such attackers are able to
+bypass security logic in the renderer process.
+For other arguments for the "defense in depth" approach and why our
+threat model covers compromised renderers, please see
+[the Site Isolation motivation](https://www.chromium.org/Home/chromium-security/site-isolation#TOC-Motivation).
+
+In a compromised renderer, an attacker is able to execute
+arbitrary native (i.e. non-JavaScript) code within the renderer
+process's sandbox.  A compromised renderer can forge
+malicious IPC messages, impersonate a Chrome Extension content script,
+or use other techniques to trick more privileged parts of the browser.
+
+The document below gives an overview of features that Chrome attempts to
+protect against attacks from a compromised renderer.  Newly discovered
+holes in this protection would be considered security bugs and possibly
+eligible for the
+[Chrome Vulnerability Rewards Program](https://www.google.com/about/appsecurity/chrome-rewards/).
+
+[TOC]
+
+
+## Site Isolation foundations
+
+Most of the other protections listed in this document implicitly assume that
+attacker-controlled execution contexts (e.g. HTML documents or service workers)
+are hosted in a separate renderer process from other, victim contexts.
+This separation is called
+[Site Isolation](https://www.chromium.org/Home/chromium-security/site-isolation)
+and allows the privileged browser
+process to restrict what origins a renderer process is authorized to read or
+control.
+
+The privilege restriction can be implemented in various ways - see the
+"protection techniques" listed in other sections in this document.
+One example is validating in the browser process whether an incoming IPC can
+legitimately claim authority over a given origin (e.g. by checking via
+`CanAccessDataForOrigin` if the process lock matches).
+Another example is making sure that capabilities handed over to renderer
+processes are origin-bound (e.g. by setting `request_initiator_site_lock`
+on a `URLLoaderFactory` given to renderer processes).
+Yet another example is making security decisions based on trustworthy knowledge,
+calculated within the privileged browser process (e.g. using
+`RenderFrameHost::GetLastCommittedOrigin()`).
+
+Compromised renderers shouldn’t be able to commit an execution context
+(e.g. commit a navigation to a HTML document, or create a service worker)
+in a renderer process hosting other, cross-site execution contexts.
+On desktop platforms all sites (site = scheme plus eTLD+1) should be isolated
+from each other.
+On Android, sites where the user entered a password should be isolated
+from each other and from other sites.
+
+**Known gaps in protection**:
+- No form of Site Isolation is active in Android WebView.
+  See also https://crbug.com/769449.
+- No form of Site Isolation is active in content hosted within
+  `<webview>` HTML tags.  See also https://crbug.com/614463.
+- Frames with `<iframe sandbox>` attribute are not isolated
+  from their non-opaque precursor origin.
+  See also https://crbug.com/510122.
+- `file:` frames may share a process with other `file:` frames.
+  See also https://crbug.com/780770.
+
+
+## Cross-Origin HTTP resources
+
+Compromised renderers shouldn't be able to read the contents (header + body) of
+a cross-site HTTP response, unless it is a valid subresource needed for
+compatibility (e.g., JavaScript, images, etc), or is successfully allowed via
+CORS.
+
+Protection techniques:
+- Enforcing
+  [Cross-Origin Read Blocking
+  (CORB)](https://www.chromium.org/Home/chromium-security/corb-for-developers)
+  in the NetworkService process
+  (i.e. before the HTTP response is handed out to the renderer process).
+- Only allowing the privileged browser process to create
+  `network::mojom::URLLoaderFactory` objects that handle HTTP requests.
+  This lets the browser process carefully control security-sensitive
+  `network::mojom::URLLoaderFactoryParams` of such factories (such as
+  `request_initiator_site_lock`, `is_corb_enabled`, `disable_web_security` or
+  `isolation_info`).
+  This also lets the CORB implementation in the NetworkService process
+  prevent spoofing of `network::ResourceRequest::request_initiator`
+  by using `network::GetTrustworthyInitiator` for comparison with
+  the trustworthy `request_initiator_site_lock`.
+
+**Known gaps in protection**:
+- Content types for which CORB does not apply
+  (e.g. `image/png`, `application/octet-stream`) are not protected by
+  default.  We recommend that HTTP servers protect such resources by
+  either serving a `Cross-Origin-Resource-Policy: same-origin` response header
+  or validating the `Sec-Fetch-Site` request header.
+- CORB protection is relaxed in presence of
+    - Adobe Flash plugin (see https://crbug.com/874515)
+    - A relatively small number of allowlisted Chrome Extensions
+      (see https://crbug.com/846346)
+
+
+## Contents of cross-site frames
+
+Compromised renderers shouldn't be able to read the contents of cross-site
+frames.  Examples:
+- Text or pixels of cross-site frames.
+- Full URL (e.g. URL path or query) of cross-site frames.
+  Note that the origin of other frames
+  needs to be exposed via `window.origin` for legacy reasons.
+
+Protection techniques:
+- Compositing tab contents (both for display and for printing)
+  outside the renderer processes.
+- Isolating PDF plugins.
+- Being careful what URLs are exposed in console messages.
+
+**Known gaps in protection**:
+- Mixed content console messages may disclose cross-site URLs
+  (see also https://crbug.com/726178).
+
+
+## Cookies
+
+Compromised renderers shouldn’t be able to read or write
+any cookies of another site,
+or `httpOnly` cookies even from the same site.
+
+Protection techniques:
+- Renderer processes are only given `network::mojom::RestrictedCookieManager`
+  for origins within their site
+  (see `StoragePartitionImpl::CreateRestrictedCookieManager`).
+- Mojo serialization does not send any cookies from HTTP headers to the renderer
+  process (see
+  `ParamTraits<scoped_refptr<net::HttpResponseHeaders>>::Write`).
+
+
+## Passwords
+
+Compromised renderers shouldn’t be able to read or write passwords of
+other sites.
+
+Protection techniques:
+- Using `CanAccessDataForOrigin` to verify IPCs sent by a renderer process
+  (e.g. `//components/password_manager/content/browser/bad_message.cc`)
+- Using trustworthy, browser-side knowledge
+  to determine which credentials to read or write
+  (e.g. `content::RenderFrameHost::GetLastCommittedURL` in
+  `password_manager::CredentialManagerImpl::GetOrigin`).
+
+
+## Security-sensitive UI/chrome elements (e.g. Omnibox)
+
+Compromised renderers shouldn’t be able to influence/spoof
+security-sensitive UI elements.
+
+Examples:
+- Omnibox
+    - URL (e.g. renderer process locked to foo.com shouldn’t
+      be able to trick the Omnibox into displaying bar.com)
+    - Secure / not secure chip (e.g. a renderer process locked to a HTTP
+      site shouldn’t be able to trick the Omnibox into displaying a
+      HTTPS-associated lock)
+    - Content settings (e.g. a renderer process that has been granted
+      microphone access shouldn’t be able to suppress the mic/camera
+      icon in the Omnibox)
+- Dialogs and prompts (for example a permissions dialog asking to allow
+  a site to show notifications)
+    - Origin in dialogs (e.g. a renderer process locked to foo.com
+      shouldn’t be able to trick the Omnibox into displaying a bar.com
+      URL in permission dialogs)
+
+Protection techniques:
+- `RenderFrameHostImpl::CanCommitOriginAndUrl` verifies that the renderer
+  process is able to commit what it claims, and kills the process otherwise.
+- Work-in-progress: calculating the origin in the browser process,
+  before a navigation commits (https://crbug.com/888079).
+
+
+## Permissions
+
+Compromised renderers shouldn’t be able to gain permissions without user
+consent.
+
+Examples: microphone access permission, geolocation permission, etc.
+
+Protection techniques:
+- Requesting permissions based on browser-side knowledge of frame's origin
+  (e.g. see `GeolocationServiceImplContext::RequestPermission`).
+
+
+## Web storage
+
+Compromised renderers shouldn’t be able to read from or write into
+storage of another site.
+
+Examples of protected storage technologies:
+- localStorage
+- sessionStorage
+- indexedDB
+- blob storage
+- webSQL
+
+Protection techniques:
+- Using `CanAccessDataForOrigin` to verify IPCs sent by a renderer process
+  (e.g. see `StoragePartitionImpl::OpenLocalStorage`).
+- Binding Mojo interfaces to a single origin obtained from browser-side
+  information in `RenderFrameHost::GetLastCommittedOrigin()`
+  (e.g. see `RenderFrameHostImpl::CreateIDBFactory`).
+
+**Known gaps in protection**:
+- https://crbug.com/917457: FileSystem API (deprecated, Chrome-only).
+
+
+## Messaging
+
+Compromised renderers shouldn’t be able to:
+- Spoof the `MessageEvent.origin` seen by a recipient of a `postMessage`.
+- Bypass enforcement of the `targetOrigin` argument of `postMessage`.
+- Send or receive `BroadcastChannel` messages for another origin.
+- Spoof the `MessageSender.origin` seen by a recipient of a
+  `chrome.runtime.sendMessage`
+  (see also [MessageSender documentation](https://developers.chrome.com/extensions/runtime#type-MessageSender) and [content script security guidance](https://groups.google.com/a/chromium.org/forum/#!topic/chromium-extensions/0ei-UCHNm34)).
+
+Protection techniques:
+- Using `CanAccessDataForOrigin` to verify IPCs sent by a renderer process
+  (e.g. in `RenderFrameProxyHost::OnRouteMessageEvent` or
+  `BroadcastChannelProvider::ConnectToChannel`).
+
+**Known gaps in protection**:
+- Spoofing of `MessageSender.id` object
+  (see [the MessageSender documentation](https://developers.chrome.com/extensions/runtime#type-MessageSender)
+  and https://crbug.com/982361).
+
+
+## JavaScript code cache
+
+Compromised renderers shouldn't be able to poison the JavaScript code cache
+used by scripts executed in cross-site execution contexts.
+
+Protection techniques:
+- Partitioning the code cache by Network Isolation Key (NIK).
+- Using `CanAccessDataForOrigin` in
+  `CodeCacheHostImpl::DidGenerateCacheableMetadataInCacheStorage`.
+
+
+## Cross-Origin-Resource-Policy response header
+
+A compromised renderer shouldn’t be able to bypass
+[Cross-Origin-Resource-Policy (CORP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy_%28CORP%29),
+which prevents or allows responses from being requested cross-origin, more
+explicitly than CORB.
+
+Protection techniques:
+- Enforcing Cross-Origin-Resource-Policy in the NetworkService process
+  (i.e. before the HTTP response is handed out to the renderer process).
+- Preventing spoofing of `network::ResourceRequest::request_initiator`
+  by using `network::GetTrustworthyInitiator` which enforces
+  browser-controlled `request_initiator_site_lock`.
+
+
+## Frame-ancestors CSP and X-Frame-Options response headers
+
+A compromised renderer shouldn’t be able to bypass `X-Frame-Options`
+or `frame-ancestors` CSP.
+
+For example, if example.com/page.html sends a `X-Frame-Options: deny` header,
+then it should never commit in a subframe, even if some renderers have
+been compromised.
+
+Protection techniques:
+- `X-Frame-Options: deny` is enforced in the browser process
+  via `content::AncestorThrottle`, an implementation of
+  `content::NavigationThrottle`.
+- `frame-ancestors` is enforced in a renderer process, but
+  this process is considered trustworthy in this scenario
+  (because it hosts the frame that is requesting protection).
+  See also https://crbug.com/759184 which tracks
+  moving this enforcement into the browser process.
+
+
+## HTTP request headers
+
+Compromised renderers shouldn’t be able to control security sensitive HTTP
+request headers like `Host` or `Sec-Fetch-Site`.
+
+Protection techniques:
+- Using `AreRequestHeadersSafe` to reject `Host` and other headers that
+  should only be generated internally within the NetworkService.
+- `Sec-Fetch-Site` is robust against spoofing of
+  `network::ResourceRequest::request_initiator` by using
+  `network::GetTrustworthyInitiator` which enforces browser-controlled
+  `request_initiator_site_lock`.
+
+**Known gaps in protection**:
+- `Origin` header.  Tracked by
+  https://crbug.com/920634 (making
+  `network::ResourceRequest::request_initiator` unspoofable without
+  having to go through `GetTrustworthyInitiator`) and
+  https://crbug.com/920638 (making
+  `network::ResourceRequest::isolated_world_origin` irrelevant for
+  security decisions).
+
+
+## (WIP) SameSite cookies
+
+Compromised renderers shouldn’t be able to send a cross-site HTTP request with
+SameSite cookies.
+
+**Work-in-progress / not protected today**.
+
+TODO(morlovich): Add details.  I assume that this requires trustworthy
+|request_initiator| (similar to the `Origin` header), but probably more
+than that.
+
+See also https://crbug.com/927967.
+
+
+## (WIP) User gestures / activations.
+
+Compromised renderers shouldn't be able to spoof user gestures to perform
+actions requiring them:
+
+- A compromised renderer should not be able to forge a gesture that affects
+  the trusted browser UI.  For example, a compromised renderer should not be
+  able to interact with the Omnibox or the WebBluetooth chooser.
+
+- A compromised renderer should not be able to forge a gesture that grants
+  extra capabilities to a web origin.   For example, a compromised renderer
+  should not be able to open an unlimited number of popup
+  windows by forging user gestures.
+  **Work-in-progress / not protected today** - see https://crbug.com/848778.
+
+
+## Web Accessible Resources of Chrome Extensions
+
+Compromised non-extension renderers shouldn’t be able to access
+non-web-accessible-resources of a Chrome Extension.
+
+Protection techniques:
+- Navigations: Enforcement in the browser process
+  via `extensions::ExtensionNavigationThrottle`, an implementation of
+  `content::NavigationThrottle`.  This relies on non-spoofability
+  of `content::NavigationHandle::GetInitiatorOrigin`.
+- Subresources: Enforcement in the browser process via
+  `ExtensionURLLoaderFactory::CreateLoaderAndStart`.  This relies
+  on process boundaries and therefore doesn't rely on non-spoofability
+  of `network::ResourceRequest::request_initiator`.
+
+
+## Non-Web resources
+
+Compromised *web* renderer processes shouldn’t be able to access
+*local* resources (e.g. `file://...` or `chrome://settings`).
+
+Protection techniques:
+- TODO(lukasza, nasko): need to research
+
+
+## Android-specific protection gaps
+
+Due to resource constraints, on Android platforms only some sites get a
+dedicated renderer process, isolated from other sites.
+(Current heuristic is to isolate the sites where the user has entered a password
+in the past.)
+This means that some sites are hosted in a renderer process that is
+*not* locked to any particular site.  If an attacker compromises
+an unlocked renderer process, they may try to abuse protection gaps listed
+below.
+
+**Known gaps in protection**:
+- When `CanAccessDataForOrigin` runs on the IO thread, it cannot protect
+  isolated sites against being accessed from an unlocked renderer process.
+  Some web storage protections depend on `CanAccessDataForOrigin` calls
+  on the IO thread.
+  See also https://crbug.com/764958.
+- `request_initiator_site_lock` may be missing in unlocked renderer
+  processes on Android (for example affecting protections of CORB, CORP,
+  Sec-Fetch-Site and in the future SameSite cookies and Origin
+  protections).  See also https://crbug.com/891872.
diff --git a/chromium/docs/security/faq.md b/chromium/docs/security/faq.md
index f6a491c1d52..d0e30010c84 100644
--- a/chromium/docs/security/faq.md
+++ b/chromium/docs/security/faq.md
@@ -158,15 +158,15 @@ in web sites. The XSS Auditor was [removed in Chrome 78](https://groups.google.c
 People sometimes report that they can compromise Chrome by installing a
 malicious DLL in a place where Chrome will load it, by hooking APIs (e.g. [Issue
 130284](https://crbug.com/130284)), or by otherwise altering the configuration
-of the PC.
+of the device.
 
 We consider these attacks outside Chrome's threat model, because there is no way
 for Chrome (or any application) to defend against a malicious user who has
-managed to log into your computer as you, or who can run software with the
+managed to log into your device as you, or who can run software with the
 privileges of your operating system user account. Such an attacker can modify
 executables and DLLs, change environment variables like `PATH`, change
 configuration files, read any data your user account owns, email it to
-themselves, and so on. Such an attacker has total control over your computer,
+themselves, and so on. Such an attacker has total control over your device,
 and nothing Chrome can do would provide a serious guarantee of defense. This
 problem is not special to Chrome ­— all applications must trust the
 physically-local user.
@@ -245,7 +245,10 @@ URLs in the URL bar (to limit
 but users are otherwise free to invoke script against pages using either the URL
 bar or the DevTools console.
 
-Similarly, users may create bookmarks pointed at JavaScript URLs that will run
+<a name="TOC-Does-executing-JavaScript-from-a-bookmark-mean-there-s-an-XSS-vulnerability-"></a>
+## Does executing JavaScript from a bookmark mean there's an XSS vulnerability?
+
+No. Chromium allows users to create bookmarks to JavaScript URLs that will run
 on the currently-loaded page when the user clicks the bookmark; these are called
 [bookmarklets](https://en.wikipedia.org/wiki/Bookmarklet).
 
@@ -692,3 +695,11 @@ No. PDF files have some powerful capabilities including invoking printing or
 posting form data. To mitigate abuse of these capabiliies, such as beaconing
 upon document open, we require interaction with the document (a "user gesture")
 before allowing their use.
+
+<a name="TOC-Why-arent-null-pointer-dereferences-considered-security-bugs-"></a>
+## Why aren't null pointer dereferences considered security bugs?
+
+Null pointer dereferences with consistent, small, fixed offsets are not considered
+security bugs. A read or write to the NULL page results in a non-exploitable crash.
+If the offset is larger than a page, or if there's uncertainty about whether the
+offset is controllable, it is considered a security bug.
diff --git a/chromium/docs/security/mojo.md b/chromium/docs/security/mojo.md
index b9479610a69..fd1d2237296 100644
--- a/chromium/docs/security/mojo.md
+++ b/chromium/docs/security/mojo.md
@@ -22,7 +22,7 @@ that needs to be maintained in sync.
 
 ```c++
 interface TeleporterFactory {
-  Create(Location start, Location end) => (Teleporter);
+  Create(Location start, Location end) => (pending_remote<Teleporter>);
 };
 
 interface Teleporter {
diff --git a/chromium/docs/security/rule-of-2-drawing.png b/chromium/docs/security/rule-of-2-drawing.png
index 10aeaefba7b..611ef8aa989 100644
--- a/chromium/docs/security/rule-of-2-drawing.png
+++ b/chromium/docs/security/rule-of-2-drawing.png
diff --git a/chromium/docs/security/rule-of-2.md b/chromium/docs/security/rule-of-2.md
index 95c54c05d31..c5253352940 100644
--- a/chromium/docs/security/rule-of-2.md
+++ b/chromium/docs/security/rule-of-2.md
@@ -132,12 +132,30 @@ for an example.
 
 If you can be sure that the input comes from a trustworthy source, it can be OK
 to parse/evaluate it at high privilege in an unsafe language. A "trustworthy
-source" meets all of these criteria:
+source" means that Chromium can cryptographically prove that the data comes
+from a business entity that you can or do trust (e.g.
+for Chrome, an [Alphabet](https://abc.xyz) company).
+
+Such cryptographic proof can potentially be obtained by:
+
+  * Component Updater;
+  * The variations framework (on some platforms; see [1078056](https://crbug.com/1078056)
+    for Android and iOS limitations)
+  * Pinned TLS (see below).
+
+Pinned TLS needs to meet all these criteria to be effective:
 
   * communication happens via validly-authenticated TLS, HTTPS, or QUIC;
   * the peer's keys are [pinned in Chrome](https://cs.chromium.org/chromium/src/net/http/transport_security_state_static.json?sq=package:chromium&g=0); and
-  * the peer is operated by a business entity that you can or do trust (e.g.
-    for Chrome, an [Alphabet](https://abc.xyz) company).
+  * pinning is active on all platforms where the feature will launch.
+
+At present pinning is not enabled for all Chrome platforms. On other platforms,
+pinning may be disabled or rendered ineffective by enterprise security products.
+It is generally much better to use the Component Updater.
+
+One common pattern is to deliver a cryptographic hash of some content via such
+a trustworthy channel, but deliver the content itself via an untrustworthy
+channel. So long as the hash is properly verified, that's fine.
 
 ### Normalization {#normalization}
 
diff --git a/chromium/docs/security/severity-guidelines.md b/chromium/docs/security/severity-guidelines.md
index 7e0d6fb4587..30820436610 100644
--- a/chromium/docs/security/severity-guidelines.md
+++ b/chromium/docs/security/severity-guidelines.md
@@ -61,7 +61,8 @@ Bugs which would normally be
 critical severity with unusual mitigating factors may be rated as high severity.
 For example, renderer sandbox escapes fall into this category as their impact is
 that of a critical severity bug, but they require the precondition of a
-compromised renderer.
+compromised renderer. (Bugs which involve using [MojoJS](../../mojo/public/js/README.md)
+to trigger an exploitable browser process crash usually fall into this category).
 
 They are normally assigned priority **Pri-1** and assigned to the current stable
 milestone (or earliest milestone affected). For high severity bugs,
@@ -152,5 +153,9 @@ Example bugs:
 * An uncontrolled single-byte out-of-bounds read
 ([128163](https://crbug.com/128163)).
 
+
+## Not a security bug {#TOC-Not-a-security-bug}
+
 The [security FAQ](faq.md) covers many of the cases that we do not consider to
-be security bugs, such as [denial of service](faq.md#TOC-Are-denial-of-service-issues-considered-security-bugs-).
+be security bugs, such as [denial of service](faq.md#TOC-Are-denial-of-service-issues-considered-security-bugs-)
+and, in particular, null pointer dereferences with consistent fixed offsets.
diff --git a/chromium/docs/security/sheriff.md b/chromium/docs/security/sheriff.md
index cd479435c53..897fa7a5cd9 100644
--- a/chromium/docs/security/sheriff.md
+++ b/chromium/docs/security/sheriff.md
@@ -185,13 +185,16 @@ assigning it to someone else.
 A few components have their own triage processes or points of contact who can
 help.
 
-* V8 bugs can be assigned to the [V8 ClusterFuzz
+* V8 ClusterFuzz bugs can be assigned to the [V8 ClusterFuzz
   Sheriff](https://rotation.googleplex.com/status?id=5714662985302016) for
   triage. Note that V8 CHECK failure crashes can have security implications, so
   don't triage it yourself and instead assign it to V8 ClusterFuzz Sheriff. They
   can make an informed decision on whether it is a security vulnerability or not
   and whether it is safe to strip the security tags (**Type=Bug-Security**,
   **Restrict-View-SecurityTeam**).
+* V8 non-ClusterFuzz bugs shouldn't be assigned to the V8 ClusterFuzz sheriff.
+  Instead, Googlers should refer to [the V8 security bug triage instructions](http://go/v8-security-issue-triage-how-to)
+  for lists of component owners.
 * Skia bugs can be assigned to hcm@chromium.org. Be careful while triaging
   these! The place where we're crashing isn't necessarily the place where the
   bug was introduced, so blame may be misleading. Skia fuzzing bugs can be
@@ -203,16 +206,10 @@ help.
 
 Tips for reproducing bugs:
 
-* [https://clusterfuzz.com/upload-testcase](https://clusterfuzz.com/upload-testcase)
-  allows you to upload files to reproduce crashes on various platforms and will
-  identify revision ranges when the regression was introduced. If a test case
-  requires multiple files, they can be uploaded together in a zip or tar
-  archive. Useful fuzzers include:-
-    * repro.html [linux_asan_chrome_mp](https://clusterfuzz.com/upload-testcase?upload=true&job=linux_asan_chrome_mp)
-    or [windows_asan_chrome](https://clusterfuzz.com/upload-testcase?upload=true&job=windows_asan_chrome)
-    * repro.js [linux_asan_d8](https://clusterfuzz.com/upload-testcase?upload=true&job=linux_asan_d8)
-    * repro.pdf [libfuzzer_pdfium_asan / pdfium_fuzzer](https://clusterfuzz.com/upload-testcase?upload=true&job=libfuzzer_pdfium_asan&target=pdfium_fuzzer)
-    or [libfuzzer_pdfium_asan / pdfium_xfa_fuzzer](https://clusterfuzz.com/upload-testcase?upload=true&job=libfuzzer_pdfium_asan&target=pdfium_xfa_fuzzer)
+* Plan A is always to [use ClusterFuzz](clusterfuzz-for-sheriffs.md). As well
+  as reproducing bugs, ClusterFuzz will help you with lots of subsequent
+  bisection and labelling tasks. If it's any kind of crash, DCHECK or
+  memory safety problem, try really hard to get ClusterFuzz to reproduce it.
 * When you can't just build from a specific branch locally, check out
   [https://dev.chromium.org/getting-involved/dev-channel](https://dev.chromium.org/getting-involved/dev-channel)
   or
diff --git a/chromium/docs/security/vrp-faq.md b/chromium/docs/security/vrp-faq.md
new file mode 100644
index 00000000000..de75ca91467
--- /dev/null
+++ b/chromium/docs/security/vrp-faq.md
@@ -0,0 +1,91 @@
+# Chrome Vulnerability Reward Program FAQ
+
+[TOC]
+
+## What are the differences between the vulnerability [categories](https://www.google.com/about/appsecurity/chrome-rewards/index.html#rewards) in the Chrome VRP?
+
+We have several different classifications for security vulnerabilities that are
+reported to us. More information about each category can be found below:
+
+ * **Sandbox escape / Memory corruption in a non-sandboxed process**: a bug that
+   allows malicious code to execute in a non-sandboxed process (like the browser
+   process), or to circumvent the protections of the sandbox. (ex:
+   https://crbug.com/1025067)
+ * **Universal Cross Site Scripting (includes Site Isolation bypass)**: a flaw
+   allowing an attacker to execute script in the context of any other origin,
+   similar to how Cross Site Scripting can be leveraged against insecure
+   websites. (ex: https://crbug.com/997190)
+ * **Renderer RCE / memory corruption in a sandboxed process**: a bug that
+   allows malicious code to be executed inside a renderer or other sandboxed
+   process.  (ex: https://crbug.com/990897)
+ * **Security UI Spoofing**: a situation in which an attacker gains an
+   illegitimate advantage on a user interface surface. In Chrome this includes
+   spoofing the displayed URL or creating fake permission prompts outside of the
+   frame containing the site. (ex: https://crbug.com/1017564)
+ * **User information disclosure**: unauthorized access to information that
+   should be inaccessible to an attacker. (ex: https://crbug.com/989078)
+ * **Web Platform Privilege Escalation**: a bug that allows a site to obtain a
+   permission or capability that was not granted by a user, such as escaping an
+   iframe sandbox or bypassing cross-origin checks.
+ * **Exploitation Mitigation Bypass**: a bug which makes exploitation easier,
+   such as an out of bounds read in a sandboxed process, or which bypasses
+   security checks in Chrome. (ex:  https://crbug.com/1021457,
+   https://crbug.com/979441)
+
+User information disclosure, web platform privilege escalation and exploitation
+mitigation bypasses exist on a continuum based on how harmful they are to users.
+
+## What about rewards for Site Isolation?
+
+Site Isolation vulnerabilities are no longer receiving special rewards and will
+be categorized and rewarded as Universal Cross-site Scripting vulnerabilities.
+
+[Site Isolation](https://www.chromium.org/Home/chromium-security/site-isolation)
+makes it possible for sites (i.e., combination of scheme and eTLD+1) to run in
+dedicated renderer processes. This can mitigate [speculative side channel
+attacks](https://www.chromium.org/Home/chromium-security/ssca) as well as
+attacks from compromised renderer processes.  Site Isolation is enabled for all
+sites on desktop platforms. On Android, Site Isolation is enabled for sites
+where users enter passwords, but it does not yet mitigate compromised renderers.
+
+In scope:
+
+ * Bugs that cause two or more cross-site documents from the web to commit in
+   the same process. i.e. force pre-Site Isolation behaviour.
+ * Bugs that cause cross-site data disclosure, even if the bug assumes a
+   compromised renderer. Examples of data protected by Site Isolation: cookies,
+   saved passwords, localStorage, IndexedDB, HTTP resources covered by
+   [CORB](https://www.chromium.org/Home/chromium-security/corb-for-developers)
+   or
+   [CORP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy_(CORP)).
+
+Out of scope and known issues:
+
+ * Site Isolation on Android is not enabled for all sites or devices. Reports
+   should work when Site Isolation is enabled for the victim site (e.g., when
+   the victim site is specified in `chrome://flags/#isolate-origins`).
+ * Compromised renderers are currently out of scope for Site Isolation on
+   Android reports.
+ * Sandboxed frames and data: URLs are currently treated as the same site as
+   their creator.
+ * CORB is not enforced for the Flash plugin, which is disabled by default and
+   will be removed. CORB is also not enforced for a small set of [allowlisted
+   extensions](https://www.chromium.org/Home/chromium-security/extension-content-script-fetches),
+   until these extensions have a chance to update to the new security model.
+ * Compromised renderers can still spoof other sites (e.g., spoof Origin headers
+   or Sec-Fetch-Site headers).
+ * Timing attacks and cross-site-search attacks are out of scope and may need to
+   be mitigated by robust server-side CSRF protection.
+ * Problems in websites (e.g. missing CORB protection because of incorrect
+   Content-Type header) or
+   [extensions](https://groups.google.com/a/chromium.org/d/topic/chromium-extensions/0ei-UCHNm34/discussion)
+   (e.g., privilege escalation via messages from a compromised content script)
+   are out of scope of the Chrome VRP, but may be covered by a separate
+   website-specific or extension-specific VRP.
+
+Examples of in-scope Site Isolation issues:
+
+ * Unexpected process sharing: https://crbug.com/863069
+ * Cross-Origin Read Blocking (CORB) bypass: https://crbug.com/927849
+ * Disclosing IndexedDB data to a cross-site renderer process:
+   https://crbug.com/917668
diff --git a/chromium/docs/security/web-mitigation-metrics.md b/chromium/docs/security/web-mitigation-metrics.md
index 2314c4328ed..b8d797037c1 100644
--- a/chromium/docs/security/web-mitigation-metrics.md
+++ b/chromium/docs/security/web-mitigation-metrics.md
@@ -66,6 +66,12 @@ but also avoids relying upon `'strict-dynamic'`, via
 [script-src]: https://w3c.github.io/webappsec-csp/#directive-script-src
 [csp-is-dead]: https://research.google/pubs/pub45542/
 
+#### Embedded Enforcement
+
+`kIFrameCSPAttribute` records the overall usage of the `csp` attribute on
+`<iframe>` elements, which enables pages to enforce a policy on documents
+they embed.
+
 ## Trusted Types
 
 [Trusted Types][tt] gives page authors a means to protect their sites against
@@ -78,9 +84,10 @@ usage we obtain the following usage counts:
   two allow us to determine which percentage of pages run in enforcing or
   report-only mode (or both).
 
-* Tracking specific features: `kTrustedTypesDefaultPolicyUsed` notes whether a
-  "default" policy has been used. `kTrustedTyoesAllowDuplicates` records
-  whether an 'allow-duplicates' keyword has been used.
+* Tracking specific features: `kTrustedTypesPolicyCreated` tracks
+  creation of all Trusted Types policies, `kTrustedTypesDefaultPolicyCreated`
+  notes whether a "default" policy has been created. `kTrustedTypesAllowDuplicates` 
+  records whether an 'allow-duplicates' keyword has been used.
 
 * Error tracking: `kTrustedTypesAssignmentError` tracks whether Trusted Types
   has blocked a string assignment.
diff --git a/chromium/docs/sheriff.md b/chromium/docs/sheriff.md
index 4f2f56beb0e..2a9b6801766 100644
--- a/chromium/docs/sheriff.md
+++ b/chromium/docs/sheriff.md
@@ -400,8 +400,9 @@ hours.
 ### Other Causes
 
 There are many other things that can go wrong, which are too individually rare
-and numerous to be listed here. Ask for help with diagnosis in Slack #sheriffing
-and hopefully someone else will be able to help you figure it out.
+and numerous to be listed here. Ask for help with diagnosis in
+[slack #sheriffing] and hopefully someone else will be able to help you figure
+it out.
 
 [CI console page]: https://ci.chromium.org/p/chromium/g/chromium/console
 [SlowTests]: https://cs.chromium.org/chromium/src/third_party/blink/web_tests/SlowTests
diff --git a/chromium/docs/speed/README.md b/chromium/docs/speed/README.md
index ee9609bed52..28e76172f8e 100644
--- a/chromium/docs/speed/README.md
+++ b/chromium/docs/speed/README.md
@@ -29,6 +29,6 @@
     * Benchmark-specific discussion: benchmarking-dev@chromium.org
     <!--- TODO: Requests for new benchmarks: chrome-benchmarking-request mailing list link -->
     * Performance dashboard, bisect, try jobs: speed-services-dev@chromium.org
-  * **Chrome Speed Metrics**: provides a set of high-quality metrics that represent real-world user experience, and exposes these metrics to both Chrome and Web Developers.
+  * **[Chrome Speed Metrics](../speed_metrics/README.md)**: provides a set of high-quality metrics that represent real-world user experience, and exposes these metrics to both Chrome and Web Developers.
     * General discussion: speed-metrics-dev@chromium.org
     * The actual metrics: [speed launch metrics survey.](https://docs.google.com/document/d/1Ww487ZskJ-xBmJGwPO-XPz_QcJvw-kSNffm0nPhVpj8/edit#heading=h.2uunmi119swk)
diff --git a/chromium/docs/speed/metrics_changelog/2020_04_lcp.md b/chromium/docs/speed/metrics_changelog/2020_04_lcp.md
new file mode 100644
index 00000000000..06f158a3165
--- /dev/null
+++ b/chromium/docs/speed/metrics_changelog/2020_04_lcp.md
@@ -0,0 +1,30 @@
+# Largest Contentful Paint Changes in M81
+
+## Changes in Chrome 81
+Prior to Chrome 81, the Largest Contentful Paint (LCP) reporting logic for the
+[Chrome User Experience Report](https://developers.google.com/web/tools/chrome-user-experience-report)
+had a bug: if the largest image on the page was still loading, but the largest
+contentful paint on the page was text, the largest contentful paint would be
+recorded as the text. As of M81, it will be recorded as the largest image,
+unless the largest image does not finish loading before user input or the page
+is hidden, in which case LCP will not be recorded. [The source code of the change
+can be seen here](https://chromium-review.googlesource.com/c/chromium/src/+/1998826).
+
+## How does this affect a site's metrics?
+
+This only affects a site's metrics in the
+[Chrome User Experience Report](https://developers.google.com/web/tools/chrome-user-experience-report).
+Sites doing measurement using the [largest-contentful-paint API](https://wicg.github.io/largest-contentful-paint/)
+are unaffected.
+
+Sites with very slow loading images which are smaller than the largest text
+block on the page will have additional LCP measures which would not have been
+previously reported. Generally these are slower-loading pages, so the site's
+overall metrics may shift higher.
+
+We do not see an impact from this change in our overall metrics, so we believe
+the effect on most sites will be minimal.
+
+## When were users affected?
+
+Most users were updated to Chrome 81 the week of April 20.
\ No newline at end of file
diff --git a/chromium/docs/speed/metrics_changelog/2020_05_fid.md b/chromium/docs/speed/metrics_changelog/2020_05_fid.md
new file mode 100644
index 00000000000..8238c69d06a
--- /dev/null
+++ b/chromium/docs/speed/metrics_changelog/2020_05_fid.md
@@ -0,0 +1,39 @@
+# First Input Delay Changes in M83
+
+## Changes in Chrome 83
+
+In Chrome 83, a bug was fixed in the implementation of First Input Delay (FID).
+Prior to M83, First input delay values less than 1ms were not reported to the
+[Chrome User Experience Report (CrUX)](https://developers.google.com/web/tools/chrome-user-experience-report).
+These values have always been exposed in the
+[web API](https://github.com/WICG/event-timing#first-input-timing).
+
+[Source code for this change](https://chromium-review.googlesource.com/c/chromium/src/+/2112983).
+
+## How does this affect a site's metrics?
+
+For the CrUX data, developers often view it in terms of the percent of page
+loads which are "fast" (less than 100ms), "medium" (less than 300ms), or "slow"
+(greater than 300ms). Since events with times less than 1ms are now included,
+sites can expect to see an increase in the percent of fast sites. How much an
+individual site's metrics will be affected depends on the number of very fast
+devices loading pages and the baseline amount of work being done. Sites with
+more fast devices and less work during load will see the largest increase in
+fast page loads.
+
+* On Android, our analysis showed that the average site will have about
+  **1.5% more page loads** marked as having fast FID.
+* On Windows, our analysis showed that the average site will have
+  **1.2% more page loads** marked as having fast FID.
+
+It's still important for sites to focus on the long tail of FID, working to
+bring down bad user experiences in high percentiles.
+
+**Data from the [web API](https://github.com/WICG/event-timing#first-input-timing)
+is unaffected by this change.**
+
+## When were users affected?
+
+Chrome 83 is currently scheduled to release on May 19. This page will be updated
+with an improved estimate of how sites' metrics are impacted within two weeks of
+launch.
diff --git a/chromium/docs/speed/metrics_changelog/2020_05_lcp.md b/chromium/docs/speed/metrics_changelog/2020_05_lcp.md
new file mode 100644
index 00000000000..796cb85773c
--- /dev/null
+++ b/chromium/docs/speed/metrics_changelog/2020_05_lcp.md
@@ -0,0 +1,36 @@
+# Largest Contentful Paint Changes in M83
+
+## Changes in Chrome 83
+
+Two bugs in the implementation of Largest Contentful Paint (LCP) were fixed
+in Chrome 83:
+ * Largest Contentful Paint measurement should stop at the first input or
+   scroll on the page. In Chrome 83, inputs and scrolls in subframes were
+   correctly accounted for. [Source code for this
+   change](https://chromium-review.googlesource.com/c/chromium/src/+/2083861).
+ * When comparing sizes of images for Largest Contentful Paint, the visual size
+   of a background image was previously computed as the size of its Layout
+   Object. This is not correct in all cases; for example in the case of CSS
+   styles like :first-letter. This issue was fixed in Chrome 83. [Source code
+   for this change](https://chromium-review.googlesource.com/c/chromium/src/+/2023523).
+
+## How does this affect a site's metrics?
+
+For the change that stops measuring LCP at input or scroll in any frame, we see
+a reduction in LCP at the higher percentiles on Android only (not desktop).
+Across all sites that use frames, we see the following impact. Sites should
+expect to see different impacts depending on how they use frames.
+
+ * At the 75th percentile, a ~5% drop
+ * At the 99th percentile, a ~40% drop
+
+We do not see an impact from the background image change in our overall metrics,
+so we believe the effect on most sites will be minimal. For some sites, the
+element which is counted as the largest contentful paint could change, and the
+metric change would depend on the layout of the site.
+
+## When were users affected?
+
+Chrome 83 is currently scheduled to release on May 19. This page will be updated
+with an improved estimate of how sites' metrics are impacted within two weeks of
+launch.
diff --git a/chromium/docs/speed/metrics_changelog/README.md b/chromium/docs/speed/metrics_changelog/README.md
index 076baf2a327..54e552c161b 100644
--- a/chromium/docs/speed/metrics_changelog/README.md
+++ b/chromium/docs/speed/metrics_changelog/README.md
@@ -1,11 +1,11 @@
-# Metrics Changelogs
+# Web Vitals Changelogs
 
-This directory contains changelogs for our key performance metrics available via web performance APIs:
+This directory contains changelogs for [Web Vitals](https://web.dev/vitals/) available via web performance APIs:
 
- * [First Contentful Paint](fcp.md)
  * [Largest Contentful Paint](lcp.md)
  * [First Input Delay](fid.md)
  * [Cumulative Layout Shift](cls.md)
+ * [First Contentful Paint](fcp.md)
 
 See also:
 
diff --git a/chromium/docs/speed/metrics_changelog/cls.md b/chromium/docs/speed/metrics_changelog/cls.md
index c97e518cf99..6715389f650 100644
--- a/chromium/docs/speed/metrics_changelog/cls.md
+++ b/chromium/docs/speed/metrics_changelog/cls.md
@@ -1,5 +1,7 @@
 # Cumulative Layout Shift Changelog
 
+This is a list of changes to [Cumulative Layout Shift](https://web.dev/cls).
+
 * Chrome 79
   * Metric is elevated to stable; changes in metric definition will be reported in this log.
 * Chrome 77
diff --git a/chromium/docs/speed/metrics_changelog/fcp.md b/chromium/docs/speed/metrics_changelog/fcp.md
index d858d4e78eb..1d8545c469a 100644
--- a/chromium/docs/speed/metrics_changelog/fcp.md
+++ b/chromium/docs/speed/metrics_changelog/fcp.md
@@ -1,5 +1,7 @@
 # First Contentful Paint Changelog
 
+This is a list of changes to [First Contentful Paint](https://web.dev/fcp).
+
 * Chrome 77
   * Metric definition improvement: [First Contentful Paint ending switches from swap time to presentation time](2019_12_fcp.md)
   * Chrome performance regression: [First Contentful Paint regression (recovered in Chrome 78)](2019_12_fcp.md)
diff --git a/chromium/docs/speed/metrics_changelog/fid.md b/chromium/docs/speed/metrics_changelog/fid.md
index 12dc54fa073..68b1a494acd 100644
--- a/chromium/docs/speed/metrics_changelog/fid.md
+++ b/chromium/docs/speed/metrics_changelog/fid.md
@@ -1,5 +1,9 @@
 # First Input Delay Changelog
 
+This is a list of changes to [First Input Delay](https://web.dev/fid).
+
+* Chrome 83
+  * Metric definition improvement: [First Input Delay includes inputs with delays &lt; 1ms in Chrome User Experience Report](2020_05_fid.md)
 * Chrome 77
   * Metric exposed via API: [First Input Delay](https://web.dev/fid/) available via [Event Timing API](https://github.com/tdresser/event-timing#first-input-timing)
 * Chrome 75
diff --git a/chromium/docs/speed/metrics_changelog/lcp.md b/chromium/docs/speed/metrics_changelog/lcp.md
index 342df274de2..80aabcf4335 100644
--- a/chromium/docs/speed/metrics_changelog/lcp.md
+++ b/chromium/docs/speed/metrics_changelog/lcp.md
@@ -1,5 +1,12 @@
 # Largest Contentful Paint Changelog
 
+This is a list of changes to [Largest Contentful Paint](https://web.dev/lcp).
+
+* Chrome 83
+  * Metric definition improvement: [Largest Contentful Paint measurement stops at first input or scroll](2020_05_lcp.md)
+  * Metric definition improvement: [Largest Contentful Paint properly accounts for visual size of background images](2020_05_lcp.md)
+* Chrome 81
+  * Metric definition improvement: [Largest Text Paint correctly reported while largest image is loading](2020_04_lcp.md)
 * Chrome 79
   * Metric is elevated to stable; changes in metric definition will be reported in this log.
 * Chrome 77
diff --git a/chromium/docs/speed_metrics/OWNERS b/chromium/docs/speed_metrics/OWNERS
new file mode 100644
index 00000000000..2bf71fe278e
--- /dev/null
+++ b/chromium/docs/speed_metrics/OWNERS
@@ -0,0 +1 @@
+# COMPONENT: Blink>PerformanceAPIs
\ No newline at end of file
diff --git a/chromium/docs/speed_metrics/README.md b/chromium/docs/speed_metrics/README.md
new file mode 100644
index 00000000000..2b02a89ae8d
--- /dev/null
+++ b/chromium/docs/speed_metrics/README.md
@@ -0,0 +1,106 @@
+# Chrome Speed Metrics
+
+[TOC]
+
+## Mission
+The Chrome Speed Metrics team aims to quantify users' experience of the web to
+provide Chrome engineers and web developers the metrics, insights, and
+incentives they need to improve it. We aim to:
+
+  * **Quantify** web UX via a high quality set of UX metrics which Chrome devs
+    align on.
+  * **Expose** these metrics consistently to Chrome and Web devs, in the lab and
+    the wild.
+  * **Analyze** these metrics, producing actionable reports driving our UX
+    efforts.
+  * **Own** implementation for these metrics for TBMv2, UMA/UKM, and web perf
+    APIs.
+
+## Goals
+
+### Quantify Users’ Experience of the Web
+Chrome needs a small, consistent set of high quality user experience metrics.
+Chrome Speed Metrics is responsible for authoring reference implementations of
+these metrics implemented using Trace Based Metrics v2 (TBMv2) in
+[tracing/metrics](https://source.chromium.org/chromium/chromium/src/+/master:third_party/catapult/tracing/tracing/metrics/).
+These reference implementations will often require adding C++ instrumentation.
+Some metrics work will also be driven by more focused metrics teams, such as the
+work on Frame Throughput. Chrome Speed Metrics also owns UMA/UKM metrics, and
+speed metrics related Web Perf APIs.
+
+The wider set of folks involved in defining these metrics will include:
+
+  * Area domain experts.
+  * Focused metrics teams.
+  * Devtools folks.
+  * DevX, documenting what these metrics mean for external developers.
+  * Occasional other experts (e.g., UMA folks).
+
+### Expose Consistent Metrics Everywhere
+Chrome Speed Metrics is responsible for ensuring that our core metrics are
+exposed everywhere. This includes collaborating with devtools, lighthouse, etc.
+to make sure our metrics are easy to expose, and are exposed effectively.
+
+### Analyze Chrome Performance, providing data to drive our performance efforts
+Metrics aren’t useful if no one looks at them. Chrome Speed Metrics performs
+detailed analysis on our key metrics and breakdown metrics, providing actionable
+reports on how Chrome performs in the lab and in the wild. These reports are
+used to guide regular decision making processes as part of Chrome’s planning
+cycle, as well as to inspire Chrome engineers with concrete ideas for how to
+improve Chrome’s UX.
+
+### Own Core Metrics
+The Chrome Speed Metrics team will gradually gain ownership of
+[tracing/metrics](https://source.chromium.org/chromium/chromium/src/+/master:third_party/catapult/tracing/tracing/metrics/),
+and will be responsible for the long term code health of this directory. We’re
+also ramping up ownership in the Web Perf API space.
+
+## Contact information
+  * **Email**: speed-metrics-dev@chromium.org
+  * **Tech lead**: sullivan@chromium.org
+  * **File a bug**:
+    * For issues related to web performance APIs, file a bug
+      [here](https://bugs.chromium.org/p/chromium/issues/entry?template=Defect+report+from+developer&components=Blink%3EPerformanceAPIs)
+    * For other kinds of issues, file a bug
+      [here](https://bugs.chromium.org/p/chromium/issues/entry?template=Defect+report+from+developer&components=Speed%3EMetrics)
+
+## APIs we own
+  * [Element Timing](https://github.com/WICG/element-timing)
+  * [Event Timing](https://github.com/WICG/event-timing)
+  * [HR Time](https://github.com/w3c/hr-time/)
+  * [Largest Contentful Paint](https://github.com/WICG/largest-contentful-paint)
+  * [Layout Instability](https://github.com/WICG/layout-instability)
+  * [Longtasks](https://github.com/w3c/longtasks/)
+  * We own some of the implementation details of [Navigation
+    Timing](https://github.com/w3c/navigation-timing/)
+  * We are ramping up on [Page
+    Visibility](https://github.com/w3c/page-visibility/)
+  * [Paint Timing](https://github.com/w3c/paint-timing/)
+  * [Performance Timeline](https://github.com/w3c/performance-timeline)
+  * We own some of the implementation details of [Resource
+    Timing](https://github.com/w3c/resource-timing)
+  * [User Timing](https://github.com/w3c/user-timing)
+
+## Web performance objectives
+  * See our [web performance objectives](webperf_okrs.md).
+
+## Metrics changelog
+We realize it's important to keep developers on the loop regarding important
+changes to our metric definitions. For this reason, we have created a [metrics
+changelog](../speed/metrics_changelog/README.md) which will be updated over time.
+
+## User Docs
+  * [Metrics for web developers](https://web.dev/metrics/).
+  * [Properties of a good metric](../speed/good_toplevel_metrics.md)
+  * [Survey of current
+    metrics](https://docs.google.com/document/d/1Ww487ZskJ-xBmJGwPO-XPz_QcJvw-kSNffm0nPhVpj8/edit)
+
+## Talks
+  * [Lessons learned from performance monitoring in
+    Chrome](https://www.youtube.com/watch?v=ctavZT87syI), by Annie Sullivan.
+  * [Shipping a performance API on
+    Chromium](https://ftp.osuosl.org/pub/fosdem/2020/H.1309/webperf_chromium_development.webm),
+    by Nicolás Peña Moreno.
+  * [Understanding Cumulative Layout
+    Shift](https://www.youtube.com/watch?v=zIJuY-JCjqw), by Annie Sullivan and
+    Steve Kobes.
\ No newline at end of file
diff --git a/chromium/docs/speed_metrics/webperf_okrs.md b/chromium/docs/speed_metrics/webperf_okrs.md
new file mode 100644
index 00000000000..87015e70647
--- /dev/null
+++ b/chromium/docs/speed_metrics/webperf_okrs.md
@@ -0,0 +1,121 @@
+# Web Performance Objectives
+
+[TOC]
+
+## 2020 Q2
+
+### New web performance APIs
+
+  * Work towards shipping
+    **[performance.measureMemory](https://github.com/WICG/performance-measure-memory)**.
+    This API intends to provide memory measurements for web pages without
+    leaking information. It will replace the non-standard performance.memory and
+    provide more accurate information, but will require the website to be
+    [cross-origin
+    isolated](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/crossOriginIsolated).
+    Try it out with the Origin Trial
+    [here](https://web.dev/monitor-total-page-memory-usage/#using-performance.measurememory())!
+    Deliverables for this quarter:
+    * Extend the scope of the API to workers.
+    * Draft a spec.
+
+  * Work towards web perf support for **Single Page Apps** (SPAs). SPAs have
+    long been mistreated by our web performance APIs, which mostly focus on the
+    initial page load for ‘multi-page apps’. It will be a long process to
+    resolve all measurement gaps, but we intend to start making progress on
+    better performance measurements for SPAs by using a data-driven approach.
+    Deliverables for this quarter:
+    * Implement a strategy for measuring the performance of SPA navigations in
+      RUM, based on explicit navigation annotations via User Timing.
+    * Partner with some frameworks to gather data using said strategy.
+    * Socialize an explainer with our ideas.
+
+  * Work towards web perf support for **page abandonment**. Currently, our APIs
+    are blind to a class of users that decide to leave the website very early
+    on, before the performance measurement framework of the website is set into
+    place. This quarter, we plan to create and socialize a proposal about
+    measuring early page abandonment.
+
+  * Ship the full **[Event Timing](https://github.com/WICG/event-timing)** API.
+    Currently, Chrome ships only ‘first-input’ to enable users to measure their
+    [First Input Delay](https://web.dev/fid/). We intend to ship support for
+    ‘event’ so that developers can track all slow events. Each entry will
+    include a ‘target’ attribute to know which was the EventTarget. We’ll
+    support a durationThreshold parameter in the observer to tweak the duration
+    of events being observed. Finally, we’ll also have performance.eventCounts
+    to enable computing estimated percentiles based on the data received.
+
+  * Ship a **[Page Visibility](https://github.com/w3c/page-visibility/)**
+    observer. Right now, the Page Visibility API allows registering an event
+    listener for future changes in visibility, but any visibility states prior
+    to that are missed. The solution to this is having an observer which enables
+    ‘buffered’ entries, so a full history of the visibility states of the page
+    is available. An alternative considered was having a boolean flag in the
+    PerformanceEntry stating that the page was backgrounded before the entry was
+    created, but there was overwhelming
+    [support](https://lists.w3.org/Archives/Public/public-web-perf/2020Apr/0005.html)
+    for the observer instead.
+
+  * Provide support for two Facebook-driven APIs:
+    [isInputPending](https://github.com/WICG/is-input-pending) and [JavaScript
+    Self-Profiling](https://github.com/WICG/js-self-profiling). The
+    **isInputPending** API enables developers to query whether the browser has
+    received but not yet processed certain kinds of user inputs. This way, work
+    can be scheduled on longer tasks while still enabling the task to stopped
+    when higher priority work arises. The **JS Self-Profiling** API enables
+    developers to collect JS profiles from real users, given a sampling rate and
+    capacity. It enables measuring the performance impact of specific JS
+    functions and finding hotspots in JS code.
+
+### Existing web performance API improvements
+
+* Ship the
+  [sources](https://github.com/WICG/layout-instability#Source-Attribution)
+  attribute for the
+  **[LayoutInstability](https://github.com/WICG/layout-instability)** API. The
+  Layout Instability API provides excellent information about content shifting
+  on a website. This API is already shipped in Chrome. However, it’s often hard
+  to figure out which content is shifting. This new attribute will inform
+  developers about the shifting elements and their locations within the
+  viewport.
+
+* **[LargestContentfulPaint](https://github.com/WICG/largest-contentful-paint)**:
+  gather data about LCP without excluding DOM nodes that were removed. The
+  Largest Contentful Paint API exposes the largest image or text that is painted
+  in the page. Currently, content removed from the website is also removed as a
+  candidate for LCP. However, this negatively affects some websites, for
+  instance those with certain types of image carousels. This quarter, we’ll
+  gather data internally to determine whether we should start including removed
+  DOM content. The API itself will not change for now.
+
+* _(Stretch)_ Work on exposing the **‘final’ LargestContentfulPaint** candidate.
+  Currently LCP just emits a new entry whenever a new candidate is found. This
+  means that a developer has no way to know when LCP is ‘done’, which can happen
+  early on if there is some relevant user input in the page. We could consider
+  surfacing an entry to indicate that LCP computations are finished and
+  including the final LCP value, when possible. There’s also an
+  [idea](https://github.com/WICG/largest-contentful-paint/issues/43#issuecomment-608569132)
+  to include some heuristics to get a higher quality signal regarding whether
+  the LCP obtained seems ‘valid’. If we have time this quarter, we’d be happy to
+  do some exploration on this.
+
+* _(Stretch)_ **[ResourceTiming](https://github.com/w3c/resource-timing)**:
+  outline a plan to fix the problem of TAO (Timing-Allow-Origin) being an opt-in
+  for non-timing information such as transferSize. This may mean using a new
+  header or relying on some of the upcoming new security primitives in the web.
+  If we have time this quarter, we’d like to begin tackling this problem by
+  socializing a concrete proposal for a fix.
+
+### Interop and documentation
+
+* **[Paint Timing](https://github.com/w3c/paint-timing)**: change the Chromium
+  implementation so it passes [new web platform
+  tests](https://wpt.fyi/results/paint-timing/fcp-only?label=experimental&label=master&aligned).
+  These tests are based on the feedback from WebKit. They intend to ship First
+  Contentful Paint in the near future!
+
+* Improve the **documentation** of our APIs on MDN and web.dev. We have been
+  busily shipping new web perf APIs, but some of the documentation of them has
+  lagged behind. For instance, we’ll make sure that there’s MDN pages on all of
+  the new APIs we’ve shipped, and we’ll collaborate with DevRel to ensure that
+  the documentation on web.dev is accurate.
diff --git a/chromium/docs/static_initializers.md b/chromium/docs/static_initializers.md
index 8226922eef1..0eea3fcc0a6 100644
--- a/chromium/docs/static_initializers.md
+++ b/chromium/docs/static_initializers.md
@@ -27,9 +27,16 @@ For Linux:
 
     tools/linux/dump-static-initializers.py out/Release/chrome
 
-For Android:
-
-    build/android/resource_sizes.py --chromium-output-directory out/Release --dump-static-initializers out/Release/apks/MonochromePublic.apk
-    tools/binary_size/diagnose_bloat.py HEAD
-
-For more information about `diagnose_bloat.py`, refer to its [README.md](../tools/binary_size/README.md)
+For Android (from easiest to hardest):
+
+    # Build with: is_official_build=true is_chrome_branded=true
+    # This will dump the list of SI's only when they don't match the expected
+    # number in static_initializers.gni (this is what the bots use).
+    ninja chrome/android:monochrome_static_initializers
+    # or:
+    tools/binary_size/diagnose_bloat.py HEAD  # See README.md for flags.
+    # or:
+    tools/linux/dump-static-initializers.py --toolchain-prefix third_party/android_ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/arm-linux-androideabi- out/Release/libmonochrome.so 
+
+* For more information about `diagnose_bloat.py`, refer to its [README.md](/tools/binary_size/README.md#diagnose_bloat.py)
+* List of existing static initializers documented in [static_initializers.gni](/chrome/android/static_initializers.gni)
diff --git a/chromium/docs/testing/chromeos_debugging_tips.md b/chromium/docs/testing/chromeos_debugging_tips.md
index c69f0895fdc..ca4e06c3c46 100644
--- a/chromium/docs/testing/chromeos_debugging_tips.md
+++ b/chromium/docs/testing/chromeos_debugging_tips.md
@@ -30,13 +30,19 @@ the test step's [shard #0 isolated out] link. From there, view the various
 `log/chrome/...` or `log/ui/...` text files and you should find some with
 browser [crashes and stack traces].
 
-To disable a test on Chrome's builders, the preferred method is to add the
-`informational` attribute to the test's definition (see [Tast attributes] for
-more info). Note that this requires a full Chrome OS checkout. If that's not an
-option, or if it needs to be disabled ASAP, you can add it to the list of
+There a couple ways to disable a test on Chrome's builders:
+- **With a full CrOS checkout**: If you have a full CrOS checkout, you can add
+the `informational` attribute to the test's definition (see [Tast attributes]
+for more info). This can take time (ie: many hours) to land and propagate onto
+Chrome's builders. So if you need the test disabled ASAP, consult the next
+option.
+- **With only a Chromium checkout**: You can also add the test to the list of
 disabled tests for the step's GN target. For example, to disable a test in the
 `chrome_all_tast_tests` step, add it to [this list].
 
+In both cases, please make sure a bug is filed for the test, and route it to
+the appropriate owners.
+
 ## Telemetry
 
 >TODO: Add instructions for debugging telemetry failures.
diff --git a/chromium/docs/testing/web_tests.md b/chromium/docs/testing/web_tests.md
index 1201c8f89c4..5e4d188e293 100644
--- a/chromium/docs/testing/web_tests.md
+++ b/chromium/docs/testing/web_tests.md
@@ -225,7 +225,9 @@ There are two ways to run web tests with additional command-line arguments:
 
   It will also look for flag-specific expectations in
   `web_tests/FlagExpectations/blocking-repaint`, if this file exists. The
-  suppressions in this file override the main TestExpectations file.
+  suppressions in this file override the main TestExpectations files.
+  However, `[ Slow ]` in either flag-specific expectations or base expectations
+  is always merged into the used expectations.
 
   It will also look for baselines in `web_tests/flag-specific/blocking-repaint`.
   The baselines in this directory override the fallback baselines.
@@ -278,11 +280,13 @@ There are two ways to run web tests with additional command-line arguments:
   These virtual tests exist in addition to the original `compositing/...` and
   `fast/repaint/...` tests. They can have their own expectations in
   `web_tests/TestExpectations`, and their own baselines. The test harness will
-  use the non-virtual baselines as a fallback. However, the non-virtual
-  expectations are not inherited: if `fast/repaint/foo.html` is marked
-  `[ Fail ]`, the test harness still expects
-  `virtual/blocking_repaint/fast/repaint/foo.html` to pass. If you expect the
-  virtual test to also fail, it needs its own suppression.
+  use the non-virtual expectations and baselines as a fallback. If a virtual
+  test has its own expectations, they will override all non-virtual
+  expectations. otherwise the non-virtual expectations will be used. However,
+  `[ Slow ]` in either virtual or non-virtual expectations is always merged
+  into the used expectations. If a virtual test is expected to pass while the
+  non-virtual test is expected to fail, you need to add an explicit `[ Pass ]`
+  entry for the virtual test.
 
   This will also let any real tests under `web_tests/virtual/blocking_repaint`
   directory run with the `--blocking-repaint` flag.
@@ -318,6 +322,13 @@ Consider the following when choosing between them:
   in the suite or `virtual/blocking_repaint/fast/repaint/dir` to run real
   or virtual tests in the suite under a specific directory.
 
+*** note
+We can run a virtual test with additional flags. Both the virtual args and the
+additional flags will be applied. The fallback order of baselines and
+expectations will be: 1) flag-specific virtual, 2) non-flag-specific virtual,
+3) flag-specific base, 4) non-flag-specific base
+***
+
 ## Tracking Test Failures
 
 All bugs, associated with web test failures must have the
diff --git a/chromium/docs/threading_and_tasks.md b/chromium/docs/threading_and_tasks.md
index 5c8f0b3cacc..60d4ddfed5a 100644
--- a/chromium/docs/threading_and_tasks.md
+++ b/chromium/docs/threading_and_tasks.md
@@ -640,6 +640,9 @@ This avoids degenerate cases:
   to be fair to multiple same-priority requests and/or ability to request lower
   priority work to yield when high priority work comes in.
 
+See [`base/task/job_perftest.cc`](https://cs.chromium.org/chromium/src/base/task/job_perftest.cc)
+for a complete example.
+
 ```cpp
 // A canonical implementation of |worker_task|.
 void WorkerTask(base::JobDelegate* job_delegate) {
diff --git a/chromium/docs/ui/android/night_mode.md b/chromium/docs/ui/android/night_mode.md
index 2aec665654c..4d1a0bf95b4 100644
--- a/chromium/docs/ui/android/night_mode.md
+++ b/chromium/docs/ui/android/night_mode.md
@@ -112,7 +112,7 @@ If adding a new theme, make sure the parent (or any indirect ancestor) theme of
 ### Troubleshooting
 
 * Make sure `View` is inflated from `Activity` context instead of `Application` context
-  * `RemoteView` is an exception. See [RemoteViewsWithNightModeInflater.java](https://cs.chromium.org/chromium/src/chrome/android/java/src/org/chromium/chrome/browser/night_mode/RemoteViewsWithNightModeInflater.java?) for details.
+  * `RemoteView` is an exception. See [RemoteViewsWithNightModeInflater.java](https://cs.chromium.org/chromium/src/chrome/android/java/src/org/chromium/chrome/browser/night_mode/RemoteViewsWithNightModeInflater.java) for details.
 * Make sure color resources are accessed from `Activity` or `View` context instead of `Application` context
 * Check whether `Configuration.uiMode & UI_MODE_NIGHT_MASK` gives the correct UI night mode
   * If uiMode is not correct, it could be a support library issue or an Android framework issue. You can contact chrome-android-app@chromium.org for help.
@@ -125,19 +125,19 @@ Render tests are the recommended way to verify the appearance of night mode UI.
 **For tests using DummyUiActivity:**
 
 * Put all the render tests into a separate test suite
-* Use class parameter [`NightModeTestUtils.NightModeParams.class`](https://cs.chromium.org/chromium/src/chrome/android/javatests/src/org/chromium/chrome/browser/night_mode/NightModeTestUtils.java?type=cs&q=NightModeTestUtils.NightModeParams)
+* Use class parameter [`NightModeTestUtils.NightModeParams.class`](https://cs.chromium.org/chromium/src/ui/android/javatests/src/org/chromium/ui/test/util/NightModeTestUtils.java?type=cs&q=NightModeTestUtils.NightModeParams)
 * Pass in a boolean parameter that indicates night mode state in constructor
-* Set up night mode in constructor by calling [`NightModeTestUtils#setUpNightModeForDummyUiActivity()`](https://cs.chromium.org/chromium/src/chrome/android/javatests/src/org/chromium/chrome/browser/night_mode/NightModeTestUtils.java?type=cs&q=setUpNightModeForDummyUiActivity&sq=package:chromium) and [`RenderTestRule#setNightModeEnabled()`](https://cs.chromium.org/chromium/src/chrome/test/android/javatests/src/org/chromium/chrome/test/util/RenderTestRule.java?type=cs&q=setNightModeEnabled)
-* During [`tearDownTest()`](https://cs.chromium.org/chromium/src/ui/android/javatests/src/org/chromium/ui/test/util/DummyUiActivityTestCase.java?type=cs&q=tearDownTest), reset night mode state by calling [`NightModeTestUtils#tearDownNightModeForDummyUiActivity()`](https://cs.chromium.org/chromium/src/chrome/android/javatests/src/org/chromium/chrome/browser/night_mode/NightModeTestUtils.java?type=cs&q=tearDownNightModeForDummyUiActivity)
+* Set up night mode in constructor by calling [`NightModeTestUtils#setUpNightModeForDummyUiActivity()`](https://cs.chromium.org/chromium/src/ui/android/javatests/src/org/chromium/ui/test/util/NightModeTestUtils.java?type=cs&q=setUpNightModeForDummyUiActivity&sq=package:chromium) and [`RenderTestRule#setNightModeEnabled()`](https://cs.chromium.org/chromium/src/ui/android/javatests/src/org/chromium/ui/test/util/RenderTestRule.java?type=cs&q=setNightModeEnabled)
+* During [`tearDownTest()`](https://cs.chromium.org/chromium/src/ui/android/javatests/src/org/chromium/ui/test/util/DummyUiActivityTestCase.java?type=cs&q=tearDownTest), reset night mode state by calling [`NightModeTestUtils#tearDownNightModeForDummyUiActivity()`](https://cs.chromium.org/chromium/src/ui/android/javatests/src/org/chromium/ui/test/util/NightModeTestUtils.java?type=cs&q=tearDownNightModeForDummyUiActivity)
 
 See [this CL](https://chromium-review.googlesource.com/c/chromium/src/+/1613883) as an example
 
 **For tests using ChromeActivityTestRule:**
 
-* In the method annotated with `@BeforeClass`, initialize states by calling [`NightModeTestUtils.setUpNightModeBeforeChromeActivityLaunched()`](https://cs.chromium.org/chromium/src/chrome/android/javatests/src/org/chromium/chrome/browser/night_mode/NightModeTestUtils.java?type=cs&q=setUpNightModeBeforeChromeActivityLaunched)
+* In the method annotated with `@BeforeClass`, initialize states by calling [`ChromeNightModeTestUtils.setUpNightModeBeforeChromeActivityLaunched()`](https://cs.chromium.org/chromium/src/chrome/android/javatests/src/org/chromium/chrome/browser/night_mode/ChromeNightModeTestUtils.java?type=cs&q=setUpNightModeBeforeChromeActivityLaunched)
 * Add method `setupNightMode()` with annotation `@ParameterAnnotations.UseMethodParameterBefore(NightModeTestUtils.NightModeParams.class)`
-* In method `setupNightMode()`, set up night mode state by calling [`NightModeTestUtils#setUpNightModeForChromeActivity()`](https://cs.chromium.org/chromium/src/chrome/android/javatests/src/org/chromium/chrome/browser/night_mode/NightModeTestUtils.java?type=cs&q=setUpNightModeForChromeActivity) and [`RenderTestRule#setNightModeEnabled()`](https://cs.chromium.org/chromium/src/chrome/test/android/javatests/src/org/chromium/chrome/test/util/RenderTestRule.java?type=cs&q=setNightModeEnabled)
-* In the method annotated with `@AfterClass`, reset night mode state by calling [`tearDownNightModeAfterChromeActivityDestroyed`](https://cs.chromium.org/chromium/src/chrome/android/javatests/src/org/chromium/chrome/browser/night_mode/NightModeTestUtils.java?type=cs&q=tearDownNightModeAfterChromeActivityDestroyed)
+* In method `setupNightMode()`, set up night mode state by calling [`ChromeNightModeTestUtils#setUpNightModeForChromeActivity()`](https://cs.chromium.org/chromium/src/chrome/android/javatests/src/org/chromium/chrome/browser/night_mode/ChromeNightModeTestUtils.java?type=cs&q=setUpNightModeForChromeActivity) and [`RenderTestRule#setNightModeEnabled()`](https://cs.chromium.org/chromium/src/ui/android/javatests/src/org/chromium/ui/test/util/RenderTestRule.java?type=cs&q=setNightModeEnabled)
+* In the method annotated with `@AfterClass`, reset night mode state by calling [`tearDownNightModeAfterChromeActivityDestroyed`](https://cs.chromium.org/chromium/src/chrome/android/javatests/src/org/chromium/chrome/browser/night_mode/ChromeNightModeTestUtils.java?type=cs&q=tearDownNightModeAfterChromeActivityDestroyed)
 
 See [this CL](https://chromium-review.googlesource.com/c/chromium/src/+/1656668) as an example
 
@@ -155,7 +155,7 @@ Ways to turn on night mode on **custom tab**:
 * Turn on power save mode (aka **battery saver**) on Android P+
 * Go to **Android Settings -> Developer options -> Night mode** on Android P
 * Go to **Android Settings -> Display -> Theme** on Android Q
-* [Set color scheme](https://cs.chromium.org/chromium/src/third_party/android_sdk/androidx_browser/browser/src/main/java/androidx/browser/customtabs/CustomTabsIntent.java?) to `COLOR_SCHEME_DARK` on creating a `CustomTabsIntent.Builder`
+* [Set color scheme](https://cs.chromium.org/chromium/src/third_party/android_sdk/androidx_browser/src/browser/browser/src/main/java/androidx/browser/customtabs/CustomTabsIntent.java) to `COLOR_SCHEME_DARK` on creating a `CustomTabsIntent.Builder`
 
 Some tips:
 
diff --git a/chromium/docs/ui/android/overview.md b/chromium/docs/ui/android/overview.md
index 20c91112a8d..00439d96d7a 100644
--- a/chromium/docs/ui/android/overview.md
+++ b/chromium/docs/ui/android/overview.md
@@ -12,7 +12,7 @@ Android has a number of [developer guides](https://developer.android.com/guide)
 
 ## Colors and text styles
 
-Chrome for Android has a color palette defined in [//ui/android/java/res/values/color_palette.xml](/ui/android/java/res/values/color_palette.xml) and a set of reusable semantic colors defined in [//ui/android/java/res/values/semantc_colors_adaptive.xml](/ui/android/java/res/values/semantc_colors_adaptive.xml). The semantic colors from semantc_colors_adaptive.xml should be used to ensure colors adapt properly for dark mode and can be consistently and easily updated during product-wide visual refreshes.
+Chrome for Android has a color palette defined in [//ui/android/java/res/values/color_palette.xml](/ui/android/java/res/values/color_palette.xml) and a set of reusable semantic colors defined in [//ui/android/java/res/values/semantic_colors_adaptive.xml](/ui/android/java/res/values/semantic_colors_adaptive.xml). The semantic colors from semantc_colors_adaptive.xml should be used to ensure colors adapt properly for dark mode and can be consistently and easily updated during product-wide visual refreshes.
 
 For more information on selecting the right color, see [Night Mode on Chrome Android](night_mode.md).
 
diff --git a/chromium/docs/ui/ask/index.md b/chromium/docs/ui/ask/index.md
new file mode 100644
index 00000000000..70bdcbc292d
--- /dev/null
+++ b/chromium/docs/ui/ask/index.md
@@ -0,0 +1,52 @@
+# Contact Us
+
+Need to ask a question? You can contact us with one of the methods below.
+
+## Desktop
+
+|||---|||
+
+### **Chat**
+
+[Slack desktop-ui Chromium Channel](https://chromium.slack.com/archives/CGL100B7H)
+
+Ask short questions here.
+
+Requires a Slack account.
+
+### **Discuss**
+
+[Chromium UI Discussion](https://groups.google.com/a/chromium.org/forum/#!forum/ui)
+
+Browse, ask, and respond to technical and design discussions.
+
+Asking and responding require a Google account.
+
+### **E-mail**
+
+[ui@chromium.org](mailto:ui@chromium.org)
+
+Post to [Chromium UI Discussion](https://groups.google.com/a/chromium.org/forum/#!forum/ui)
+without a Google account.
+
+|||---|||
+
+---
+
+Google Internal Resources
+
+|||---|||
+
+#####
+
+[Desktop UI Channel](https://chat.google.com/room/AAAA0vhHCUE)
+
+#####
+
+[Desktop UI Discussion](https://groups.google.com/a/google.com/forum/#!forum/chrome-desktop-ui)
+
+#####
+
+[chrome-desktop-ui@google.com](mailto:chrome-desktop-ui@google.com)
+
+|||---|||
diff --git a/chromium/docs/ui/ask/navbar.md b/chromium/docs/ui/ask/navbar.md
new file mode 100644
index 00000000000..1a3ce731996
--- /dev/null
+++ b/chromium/docs/ui/ask/navbar.md
@@ -0,0 +1,9 @@
+# Ask about Chromium UI
+
+* [Chromium Docs Home](/docs/README.md)
+* [Chromium UI](/docs/ui/index.md)
+* [Create](/docs/ui/create/index.md)
+* [Learn](/docs/ui/learn/index.md)
+* [Ask](/docs/ui/ask/index.md)
+
+[home]: /docs/ui/ask/index.md
diff --git a/chromium/docs/ui/create/index.md b/chromium/docs/ui/create/index.md
new file mode 100644
index 00000000000..0454d20cc90
--- /dev/null
+++ b/chromium/docs/ui/create/index.md
@@ -0,0 +1,4 @@
+# Creating with Chromium UI
+
+# Recipes
+Coming soon.
diff --git a/chromium/docs/ui/create/navbar.md b/chromium/docs/ui/create/navbar.md
new file mode 100644
index 00000000000..126fc004341
--- /dev/null
+++ b/chromium/docs/ui/create/navbar.md
@@ -0,0 +1,9 @@
+# Create with Chromium UI
+
+* [Chromium Docs Home](/docs/README.md)
+* [Chromium UI](/docs/ui/index.md)
+* [Create](/docs/ui/create/index.md)
+* [Learn](/docs/ui/learn/index.md)
+* [Ask](/docs/ui/ask/index.md)
+
+[home]: /docs/ui/create/index.md
diff --git a/chromium/docs/ui/index.md b/chromium/docs/ui/index.md
index 54866b7592d..cdf7b44f158 100644
--- a/chromium/docs/ui/index.md
+++ b/chromium/docs/ui/index.md
@@ -1,7 +1,32 @@
-# Chromium UI Development
-Developing in Chromium UI? Trying to figure out how we handle bugs? You've
-reached the right place.
+# Welcome!
+Developing in Chromium UI? Trying to figure out how to create your UI? Need to
+contact the Views team? You've reached the right place.
 
-# Bug Triage
-Chromium UI Bug Triage is sharded between several teams.
-*   [Frontline Triage Procedures](frontline_triage.md)
+## Quick Links
+|||---|||
+
+### **[Create](/docs/ui/create/index.md)**
+
+Recipes to help you work with Chrome UI.
+
+* [Coming Soon]
+
+### **[Learn](/docs/ui/learn/index.md)**
+
+Details on Chrome UI.
+
+* [Best Practices](/docs/ui/learn/index.md#best-practices)
+
+Processes
+
+* [Frontline Triage Procedures](frontline_triage.md)
+
+### **[Ask](/docs/ui/ask/index.md)**
+
+Ways to get help.
+
+* [Chat](/docs/ui/ask/index.md#chat)
+* [Discuss](/docs/ui/ask/index.md#discuss)
+* [E-mail](/docs/ui/ask/index.md#e_mail)
+
+|||---|||
diff --git a/chromium/docs/ui/learn/bestpractices/colors-upload_violation.png b/chromium/docs/ui/learn/bestpractices/colors-upload_violation.png
new file mode 100644
index 00000000000..18aadfcc841
--- /dev/null
+++ b/chromium/docs/ui/learn/bestpractices/colors-upload_violation.png
diff --git a/chromium/docs/ui/learn/bestpractices/colors-upload_violation_dark.png b/chromium/docs/ui/learn/bestpractices/colors-upload_violation_dark.png
new file mode 100644
index 00000000000..a0855bb2588
--- /dev/null
+++ b/chromium/docs/ui/learn/bestpractices/colors-upload_violation_dark.png
diff --git a/chromium/docs/ui/learn/bestpractices/colors.md b/chromium/docs/ui/learn/bestpractices/colors.md
new file mode 100644
index 00000000000..cf8a0846c37
--- /dev/null
+++ b/chromium/docs/ui/learn/bestpractices/colors.md
@@ -0,0 +1,607 @@
+# Best Practice: Colors
+
+Views best practices for color handling largely center around distinguishing how
+colors are handled physically versus logically. Physical colors are defined
+presentationally, usually as specific RGB or Material values, or occasionally
+referentially (e.g. "#202124", "Google Grey 900", or "10% white atop toolbar
+background"). Logical colors are defined functionally, and may be more or less
+specific depending on context (e.g. "body text", "call to action", "hovered
+button background", or "profile menu bottom stroke").
+
+Distinguishing logical and physical use in code makes code amenable to
+systematic changes (Material Design, Harmony, MD Refresh, dark mode...). It
+increases behavioral consistency and improves readability. It usually results in
+greater UI accessibility. Finally, it helps avoid edge case bugs that are easy
+to miss, such as problems with custom themes or the GTK native appearance.
+
+Since colors tend to get scattered across the codebase, mixed with the guidance
+on distinguishing physical and logical color use are some rules for consistent
+code organization.
+
+[TOC]
+
+## Agree on Color Function
+
+**Get UX/eng agreement on color function, not just presentation.** A mock with
+only physical values isn't amenable to the separation described above; there
+should be a rationale that describes how the various colors relate to each other
+and to the relevant specs (e.g. [Desktop Design System Guidelines](https://goto.google.com/chrome-snowglobe)
+(Internal Link)). Ideally, physical color values aren't even necessary, because
+all values refer to pre-specified concepts; if new colors are needed, UX
+leadership and the toolkit team should agree on how to incorporate them into an
+updated system.
+
+## Do Not Use Physical Values Directly In A View
+
+**Do not use physical values directly in a View.** This means avoiding
+`SkColorSet[A]RGB(...)`, `SK_ColorBLACK`, `gfx::kGoogleGrey900`, and the like.
+Instead, obtain colors by requesting them (by identifier) from an appropriate
+theming object. `View`s in `ui/` should call
+`GetNativeTheme()->GetSystemColor(id)`; `View`s in `chrome/` should call
+`GetThemeProvider()->GetColor(id)`.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Old code in `tooltip_icon.cc` used hardcoded colors:
+
+#####
+
+**Best Practice**
+
+The [current version](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/bubble/tooltip_icon.cc;l=78;drc=756282c5ac4947c7329bc8b68711c3898334018f)
+uses color IDs, allowing the icon colors to potentially be tied to other icon
+colors:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+void TooltipIcon::SetDrawAsHovered(bool hovered) {
+  SetImage(gfx::CreateVectorIcon(
+      vector_icons::kInfoOutlineIcon,
+      tooltip_icon_size_,
+
+      hovered
+          ? SkColorSetARGB(
+                0xBD, 0, 0, 0)
+          : SkColorSetARGB(
+                0xBD, 0x44, 0x44, 0x44)));
+}
+```
+
+#####
+
+``` cpp
+void TooltipIcon::SetDrawAsHovered(bool hovered) {
+  SetImage(gfx::CreateVectorIcon(
+      vector_icons::kInfoOutlineIcon,
+      tooltip_icon_size_,
+      GetNativeTheme()->GetSystemColor(
+          hovered
+              ? ui::NativeTheme::
+                    kColorId_TooltipIconHovered
+              : ui::NativeTheme::
+                    kColorId_TooltipIcon)));
+}
+```
+
+|||---|||
+
+## Set Colors in OnThemeChanged()
+
+**Set colors in an `OnThemeChanged()` override;** update elsewhere as needed.
+Theming objects are generally provided through the `Widget`, and so will be null
+in a `View`'s constructor. This isn't a problem because `View`s are not yet
+visible at construction. When a `View` is first placed in a `Widget` hierarchy,
+and any time afterward that the theme may have changed, it will receive a call
+to `OnThemeChanged()`. Thus in the majority of cases, setting colors in
+`OnThemeChanged()` handles both initial presentation and theme changes
+correctly. In cases where the color to use depends on state, both
+`OnThemeChanged()` and the state change handlers may need to call common code
+that sets the correct colors.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Old code in `native_file_system_usage_bubble_view.cc` set colors in its
+constructor since it seemed reasonable to do:
+
+#####
+
+**Best Practice**
+
+The [current version](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/views/native_file_system/native_file_system_usage_bubble_view.cc;l=196;drc=532834e1da3874a57dde3ed76511f53b8eb8ecdf)
+moves this to `OnThemeChanged()` and thus handles theme changes correctly:
+
+|||---|||
+
+
+|||---|||
+
+#####
+
+``` cpp
+explicit CollapsibleListView(ui::TableModel* model) {
+  ...
+  auto button =
+      views::CreateVectorToggleImageButton(this);
+
+
+
+
+
+
+
+
+  const SkColor icon_color =
+      ui::NativeTheme::GetInstanceForNativeUi()->
+          GetSystemColor(
+              ui::NativeTheme::
+                  kColorId_DefaultIconColor);
+  views::SetImageFromVectorIconWithColor(
+      button.get(), kCaretDownIcon,
+      ui::TableModel::kIconSize, icon_color);
+  views::SetToggledImageFromVectorIconWithColor(
+      button.get(), kCaretUpIcon,
+      ui::TableModel::kIconSize, icon_color);
+  ...
+}
+```
+
+#####
+
+``` cpp
+explicit CollapsibleListView(ui::TableModel* model) {
+  ...
+  auto button =
+      views::CreateVectorToggleImageButton(this);
+  ...
+  expand_collapse_button_ =
+      label_container->AddChildView(std::move(button));
+  ...
+}
+
+void CollapsibleListView::OnThemeChanged() {
+  views::View::OnThemeChanged();
+  const SkColor icon_color = GetNativeTheme()->
+      GetSystemColor(
+          ui::NativeTheme::kColorId_DefaultIconColor);
+
+
+  views::SetImageFromVectorIconWithColor(
+      expand_collapse_button_, kCaretDownIcon,
+      ui::TableModel::kIconSize, icon_color);
+  views::SetToggledImageFromVectorIconWithColor(
+      expand_collapse_button_, kCaretUpIcon,
+      ui::TableModel::kIconSize, icon_color);
+}
+
+```
+
+|||---|||
+
+## Only Use Colors Locally
+
+**Keep color use local.** `View`s should generally access color IDs only for
+themselves, and not get or set colors on other `View`s (e.g. children). Because
+the order of `OnThemeChanged()` calls is not guaranteed, getting a cached color
+from another `View` may return an incorrect value; and setting physical
+properties of other `View`s reduces encapsulation. Instead, convey logical state
+changes as necessary, let each `View` manage its own colors, and use file-scope
+`View` subclasses freely to define the behavior of specific `View`s.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Old code in `custom_tab_bar_view.cc` tried to keep a parent's color in sync with
+its child:
+
+#####
+
+**Best Practice**
+
+[Current version](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/views/location_bar/custom_tab_bar_view.cc;l=157;drc=ab2ca22fb75c61f7167e9b20ac88cc7a85c3be6b)
+queries a color API that is guaranteed to have an up-to-date value:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+class CustomTabBarTitleOriginView : public views::View {
+ public:
+  ...
+  SkColor GetLocationColor() const {
+    return location_label_->GetEnabledColor();
+  }
+  ...
+ private:
+  views::Label* location_label_;
+};
+```
+
+#####
+
+``` cpp
+class CustomTabBarTitleOriginView : public views::View {
+ public:
+  ...
+  SkColor GetLocationColor() const {
+    return views::style::GetColor(
+        *this, CONTEXT_BODY_TEXT_SMALL,
+        views::style::TextStyle::STYLE_PRIMARY);
+  }
+  ...
+};
+```
+
+|||---|||
+
+## Only Use Color IDs to Forward Color Information
+
+Where color information must be passed on, **use color IDs, not `SkColor` or
+`ImageSkia`**. For example, menu items with images should use
+`ImageModel::FromVectorIcon(`...`, id)`, as the other `ImageModel` factory
+functions require a physical color at some prior stage, and make handling theme
+changes difficult.
+
+|||---|||
+
+#####
+
+Old code in `recovery_install_global_error.cc` embedded colors into the icon
+stored in the menu model:
+
+#####
+
+[Current version](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/recovery/recovery_install_global_error.cc;l=70;drc=b25251f1d6bc5359794d98cda8068a94e76ad317)
+uses an `ImageModel` to convey just the logical color, allowing consumers to
+apply physical colors:
+
+|||---|||
+
+|||---|||
+
+#####
+
+**Avoid**
+
+``` cpp
+gfx::Image
+RecoveryInstallGlobalError::MenuItemIcon() {
+  return gfx::Image(gfx::CreateVectorIcon(
+      kBrowserToolsUpdateIcon,
+      ui::NativeTheme::GetInstanceForNativeUi()->
+          GetSystemColor(
+              ui::NativeTheme::
+                  kColorId_AlertSeverityHigh)));
+}
+```
+
+#####
+
+**Best Practice**
+
+``` cpp
+ui::ImageModel
+RecoveryInstallGlobalError::MenuItemIcon() {
+  return ui::ImageModel::FromVectorIcon(
+      kBrowserToolsUpdateIcon,
+      ui::NativeTheme::
+          kColorId_AlertSeverityHigh);
+}
+
+
+```
+
+|||---|||
+
+## Create New Color Identifiers for New UI
+
+For new UI, **add new, specific color identifiers**. If a mock for a new
+`FrobberMenu` UI calls for the background color to be the same as the
+`FooBarMenu` background, don't reuse `kFooBarMenuBackgroundColor` when
+implementing the new menu, as the name will no longer be accurate. Add a
+`kFrobberMenuBackgroundColor` identifier and use that instead. `ui/` code should
+add identifiers to the [`NATIVE_THEME_COLOR_IDS`](https://source.chromium.org/chromium/chromium/src/+/master:ui/native_theme/native_theme_color_id.h;l=10;drc=21c19ce054e99a4361dff61877a4197831b80e6b)
+macro; `chrome/` code should typically add to the
+[`NotOverwritableByUserThemeProperty`](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/themes/theme_properties.h;l=91;drc=cfa76e5827628eb2104df0e0b55d5d89f4a93eaf)
+enum.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Old code in `menu_controller_scroll_view_container.cc` reused a text color
+constant to paint the drop indicator, since they have the same physical color:
+
+#####
+
+**Best Practice**
+
+[Current version](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/controls/menu/submenu_view.cc;l=229;drc=7910ceae672184033abc44a287e309f14e664b5e)
+defines these as distinct logical colors with the same default physical color,
+better accommodating platforms where menu text and menu icons may differ:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+void SubmenuView::PaintChildren(
+    const PaintInfo& paint_info) {
+  ...
+  const SkColor drop_indicator_color =
+      GetNativeTheme()->GetSystemColor(
+      ui::NativeTheme::
+          kColorId_HighlightedMenuItemForegroundColor);
+  recorder.canvas()->FillRect(
+      bounds, drop_indicator_color);
+}
+```
+
+#####
+
+``` cpp
+SkColor GetAuraColor(
+    NativeTheme::ColorId color_id,
+    const NativeTheme* base_theme,
+    NativeTheme::ColorScheme color_scheme) {
+  switch (color_id) {
+    ...
+    case NativeTheme::
+        kColorId_HighlightedMenuItemForegroundColor:
+    case NativeTheme::kColorId_MenuDropIndicator:
+      return gfx::kGoogleGrey200;
+    ...
+  }
+}
+
+void SubmenuView::PaintChildren(
+    const PaintInfo& paint_info) {
+  ...
+  const SkColor drop_indicator_color =
+      GetNativeTheme()->GetSystemColor(
+          ui::NativeTheme::
+              kColorId_MenuDropIndicator);
+  recorder.canvas()->FillRect(
+      bounds, drop_indicator_color);
+}
+```
+
+|||---|||
+
+## Define Identifiers Using Relationships
+
+**Define identifiers' physical values by their relationships to other colors**.
+In most cases, new UI elements are using the same underlying concepts as other
+UI elements. So instead of `kFrobberMenuBackgroundColor` copying the definition
+of `kFooBarMenuBackgroundColor`, both menus' colors should probably be defined
+in terms of some more generic underlying concept (e.g. a common toolkit-level
+menu or background color). Even in more one-off cases, colors can still be
+relational; black text on a white background is not simply black in the
+abstract, but black because it contrasts with the background. UI colors can
+usually similarly be defined as contrasting or blending against other colors,
+using the functions in [`color_utils.h`](https://source.chromium.org/chromium/chromium/src/+/master:ui/gfx/color_utils.h;drc=2e98db0e52f3f55056783031ab9f7377d4a12ad5).
+In most cases, a correct relational definition for a color will work well in
+both light and dark mode, and custom themes as well.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Old code in `common_theme.cc` defines a disabled button color absolutely:
+
+#####
+
+**Best Practice**
+
+[Current version](https://source.chromium.org/chromium/chromium/src/+/master:ui/native_theme/common_theme.cc;l=264;drc=21c19ce054e99a4361dff61877a4197831b80e6b)
+makes it clear that the disabled color is related to the normal color:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+SkColor GetAuraColor(
+    NativeTheme::ColorId color_id,
+    const NativeTheme* base_theme,
+    NativeTheme::ColorScheme color_scheme) {
+  ...
+  switch (color_id) {
+    case NativeTheme::
+        kColorId_ProminentButtonDisabledColor:
+      return gfx::kGoogleGrey100;
+    ...
+
+
+
+
+
+  }
+}
+```
+
+#####
+
+``` cpp
+SkColor GetAuraColor(
+    NativeTheme::ColorId color_id,
+    const NativeTheme* base_theme,
+    NativeTheme::ColorScheme color_scheme) {
+  ...
+  switch (color_id) {
+    case NativeTheme::
+        kColorId_ProminentButtonDisabledColor: {
+      const SkColor bg = base_theme->GetSystemColor(
+          NativeTheme::kColorId_ButtonColor,
+          color_scheme);
+      return color_utils::BlendForMinContrast(
+          bg, bg, base::nullopt, 1.2f).color;
+    }
+    ...
+  }
+}
+```
+
+|||---|||
+
+## Keep Image Resources Theme Neutral
+
+**Use image resources that are theme-neutral**. Most vector images should not
+encode color information at all; in some cases, [badging](https://source.chromium.org/chromium/chromium/src/+/master:ui/gfx/paint_vector_icon.h;l=70;drc=7a9b1b437ae847e90ef3ac10f73991796dfe5591)
+can be used to break a vector into a common core and a set of recolorable
+overlays. Full-color raster images that work on any background color can be
+used, but images that assume a particular background color, or that are broken
+into "light" and "dark" variants, should not be used; these are problematic both
+today (with custom themes and GTK) and in the future (if we modify the default
+light/dark theme colors or Material Design palettes). These cases are tricky to
+address and generally require cooperation between the visual designer, the
+toolkit team, and the UI engineer.
+
+[Current code](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/safe_browsing/cloud_content_scanning/deep_scanning_dialog_views.cc;l=100;drc=53d4f4170d068ef7e9b6e19995b0eac0cb3cfd43)
+uses two full color raster images, one that assumes a light background and the
+other that assumes a dark background:
+
+|||---|||
+
+#####
+
+![Light](colors-upload_violation.png)
+
+
+#####
+
+![Dark](colors-upload_violation_dark.png)
+
+|||---|||
+
+An improved version could split the image into a fixed color portion and an
+uncolored portion using alpha that is programmatically computed based on the
+desired foreground color.
+
+## Do Not Use Colors Outside a View
+
+**Do not use colors outside a `View`**, since doing so correctly is difficult.
+Global access to theming objects is deprecated and will eventually be removed,
+since it's error-prone and hinders future design goals. Direct use of physical
+colors and obtaining colors from `View` instances are problematic for reasons
+given above. If you need something like this, talk to the toolkit team about the
+best approach.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Old code in `tab_strip_ui_handler.cc` uses global theming objects:
+
+#####
+
+**Best Practice**
+
+[Current version](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/webui/tab_strip/tab_strip_ui_handler.cc;l=524;drc=cfa76e5827628eb2104df0e0b55d5d89f4a93eaf)
+gets colors from its embedding `View`; this will still require the caller to
+guarantee the `View`'s colors are up to date, monitor for potential changes in
+those colors, etc.:
+
+|||---|||
+
+|||---|||
+
+#####
+
+```
+
+
+
+
+
+
+
+
+
+void TabStripUIHandler::HandleGetThemeColors(
+    const base::ListValue* args) {
+  ...
+  const ui::ThemeProvider& tp =
+      ThemeService::GetThemeProviderForProfile(
+          browser_->profile());
+  base::DictionaryValue colors;
+  colors.SetString(
+      "--tabstrip-background-color",
+      color_utils::SkColorToRgbaString(
+          tp.GetColor(
+              ThemeProperties::COLOR_FRAME)));
+  ...
+}
+```
+
+#####
+
+```
+class TabStripUIHandler
+    : public content::WebUIMessageHandler,
+      public TabStripModelObserver {
+  ...
+ private:
+  TabStripUIEmbedder* const embedder_;
+  ...
+}
+
+void TabStripUIHandler::HandleGetThemeColors(
+    const base::ListValue* args) {
+  ...
+
+
+
+  base::DictionaryValue colors;
+  colors.SetString(
+      "--tabstrip-background-color",
+      color_utils::SkColorToRgbaString(
+          embedder_->GetColor(
+              ThemeProperties::COLOR_FRAME)));
+  ...
+}
+```
+
+|||---|||
diff --git a/chromium/docs/ui/learn/bestpractices/ownership.md b/chromium/docs/ui/learn/bestpractices/ownership.md
new file mode 100644
index 00000000000..6c0a340f943
--- /dev/null
+++ b/chromium/docs/ui/learn/bestpractices/ownership.md
@@ -0,0 +1,624 @@
+# Best Practice: Ownership
+
+In the common case, a `View` instance lives within a hierarchy of `View`s, up to
+a `RootView` object that is owned by a `Widget`. Calling `AddChildView<>()`
+typically passes ownership of the child to the parent, while
+`RemoveChildView[T<>]()` gives ownership back to the caller. While other
+ownership patterns exist, newly-added code should use this one.
+
+[TOC]
+
+## Lifetime Basics
+
+Accordingly, the best practices for ownership and lifetime management in Views
+code are similar to those in the rest of Chromium, but include some details
+specific to the Views APIs.
+
+* **[Avoid bare new.](https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++-dos-and-donts.md#use-and-instead-of-bare)**
+  Use `std::make_unique<>()` when creating objects, and distinguish owning and
+  non-owning uses by [using smart and raw pointer types](https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++.md#object-ownership-and-calling-conventions).
+* **Use [the unique\_ptr<> version of View::AddChildView<>()](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/view.h;l=404;drc=7cba41605a8489bace83f380760486638a2a8a4a).**
+  This clearly conveys ownership transfer from the caller to the parent `View`.
+  It also `DCHECK()`s that `set_owned_by_client()` has not been called,
+  preventing double-ownership.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Typical code from [`dice_bubble_sync_promo_view.cc`](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/views/sync/dice_bubble_sync_promo_view.cc;l=49;drc=459f2d16a6592b1290a1c2197231d46f48f49af4)
+using bare `new`:
+
+#####
+
+**Best Practice**
+
+Rewriting using the `unique_ptr<>` version of `AddChildView<>()` is shorter and
+safer:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+...
+views::Label* title =
+    new views::Label(
+        title_text, CONTEXT_BODY_TEXT_LARGE,
+        text_style);
+
+title->SetHorizontalAlignment(
+    gfx::HorizontalAlignment::ALIGN_LEFT);
+title->SetMultiLine(true);
+AddChildView(title);
+...
+signin_button_view_ =
+    new DiceSigninButtonView(
+        account, account_icon, this,
+        /*use_account_name_as_title=*/true);
+AddChildView(signin_button_view_);
+...
+```
+
+#####
+
+``` cpp
+...
+auto* title =
+    AddChildView(
+        std::make_unique<views::Label>(
+            title_text, CONTEXT_BODY_TEXT_LARGE,
+            text_style));
+title->SetHorizontalAlignment(
+    gfx::HorizontalAlignment::ALIGN_LEFT);
+title->SetMultiLine(true);
+
+...
+signin_button_view_ =
+    AddChildView(
+        std::make_unique<DiceSigninButtonView>(
+            account, account_icon, this,
+            /*use_account_name_as_title=*/true));
+...
+```
+
+|||---|||
+
+## Avoid View::set_owned_by_client()
+
+The [`View::set_owned_by_client()`](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/view.h;l=390;drc=7cba41605a8489bace83f380760486638a2a8a4a)
+flag means that a `View` is owned by something other than its parent `View`.
+This **method is deprecated** (and will eventually be removed) since it results
+in APIs that are easy to misuse, code where ownership is unclear, and a higher
+likelihood of bugs. Needing this flag may be a signal that the `View` subclass
+in question is too heavyweight, and refactoring using MVC or a similar paradigm
+would allow a long-lived "model" or "controller" with more-transient "view"s.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Code in [`time_view.{h,cc}`](https://source.chromium.org/chromium/chromium/src/+/master:ash/system/time/time_view.h;l=35;drc=7d8bc7f807a433e6a127806e991fe780aa27ce77)
+that uses `set_owned_by_client()` to have non-parented `View`s, so it can swap
+layouts without recreating the children:
+
+#####
+
+**Best Practice**
+
+Rewriting using subclasses to encapsulate layout allows the parent to merely
+adjust visibility:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+class ASH_EXPORT TimeView : public ActionableView,
+                            public ClockObserver {
+  ...
+ private:
+
+
+
+  std::unique_ptr<views::Label> horizontal_label_;
+  ...
+  std::unique_ptr<views::Label> vertical_label_hours_;
+  std::unique_ptr<views::Label> vertical_label_minutes_;
+  ...
+};
+
+void TimeView::SetupLabels() {
+  horizontal_label_.reset(new views::Label());
+  SetupLabel(horizontal_label_.get());
+  vertical_label_hours_.reset(new views::Label());
+  SetupLabel(vertical_label_hours_.get());
+  vertical_label_minutes_.reset(new views::Label());
+  SetupLabel(vertical_label_minutes_.get());
+  ...
+}
+
+void TimeView::SetupLabel(views::Label* label) {
+  label->set_owned_by_client();
+  ...
+}
+
+
+
+
+
+
+
+
+
+
+
+void TimeView::UpdateClockLayout(
+    ClockLayout clock_layout) {
+  ...
+  if (clock_layout == ClockLayout::HORIZONTAL_CLOCK) {
+    RemoveChildView(vertical_label_hours_.get());
+    RemoveChildView(vertical_label_minutes_.get());
+    SetLayoutManager(
+        std::make_unique<views::FillLayout>());
+    AddChildView(horizontal_label_.get());
+  } else {
+    RemoveChildView(horizontal_label_.get());
+    // Remove the current layout manager since it could
+    // be the FillLayout which only allows one child.
+    SetLayoutManager(nullptr);
+    // Pre-add the children since ownership is being
+    // retained by this.
+    AddChildView(vertical_label_hours_.get());
+    AddChildView(vertical_label_minutes_.get());
+    views::GridLayout* layout =
+        SetLayoutManager(
+            std::make_unique<views::GridLayout>());
+    ...
+  }
+  Layout();
+}
+```
+
+#####
+
+``` cpp
+class ASH_EXPORT TimeView : public ActionableView,
+                            public ClockObserver {
+  ...
+ private:
+  class HorizontalLabelView;
+  class VerticalLabelView;
+  ...
+  HorizontalLabelView* horizontal_label_;
+  VerticalLabelView* vertical_label_;
+  ...
+};
+
+
+
+TimeView::HorizontalLabelView::HorizontalLabelView() {
+  SetLayoutManager(
+      std::make_unique<views::FillLayout>());
+  ...
+}
+
+TimeView::VerticalLabelView::VerticalLabelView() {
+  views::GridLayout* layout =
+        SetLayoutManager(
+            std::make_unique<views::GridLayout>());
+  ...
+}
+
+void TimeView::TimeView(ClockLayout clock_layout,
+                        ClockModel* model) {
+  ...
+  horizontal_label_ =
+     AddChildView(
+        std::make_unique<HorizontalLabelView>());
+  vertical_label_ =
+     AddChildView(
+        std::make_unique<VerticalLabelView());
+  ...
+}
+
+void TimeView::UpdateClockLayout(
+    ClockLayout clock_layout) {
+  ...
+  const bool is_horizontal =
+      clock_layout == ClockLayout::HORIZONTAL_CLOCK;
+  horizontal_label_->SetVisible(is_horizontal);
+  vertical_label_->SetVisible(!is_horizontal);
+  Layout();
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+|||---|||
+
+## Avoid Refcounting and WeakPtrs
+
+Refcounting and `WeakPtr`s may also be indicators that a `View` is doing more
+than merely displaying UI. Views objects should only handle UI. Refcounting and
+`WeakPtr` needs should generally be handled by helper objects.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Old code in `cast_dialog_no_sinks_view.{h,cc}` that used weak pointers to
+`PostDelayedTask()` to itself:
+
+#####
+
+**Best Practice**
+
+[Current version](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/views/media_router/cast_dialog_no_sinks_view.h;l=20;drc=2a147d67e51e67144257d3a405e3aafec3827513)
+eliminates lifetime concerns by using a `OneShotTimer`, which is canceled when
+destroyed:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+class CastDialogNoSinksView
+    : public views::View, public views::ButtonListener {
+  ...
+ private:
+  base::WeakPtrFactory<CastDialogNoSinksView>
+      weak_factory_{this};
+  ...
+};
+
+CastDialogNoSinksView::CastDialogNoSinksView(
+    Profile* profile) : profile_(profile) {
+  ...
+  base::PostDelayedTask(
+      FROM_HERE, {content::BrowserThread::UI},
+      base::BindOnce(
+          &CastDialogNoSinksView::ShowHelpIconView,
+          weak_factory_.GetWeakPtr()),
+      kSearchWaitTime);
+}
+```
+
+#####
+
+``` cpp
+class CastDialogNoSinksView
+    : public views::View, public views::ButtonListener {
+  ...
+ private:
+  base::OneShotTimer timer_;
+  ...
+};
+
+
+CastDialogNoSinksView::CastDialogNoSinksView(
+    Profile* profile) : profile_(profile) {
+  ...
+  timer_.Start(
+      FROM_HERE, kSearchWaitTime,
+      base::BindOnce(
+          &CastDialogNoSinksView::SetHelpIconView,
+          base::Unretained(this)));
+}
+
+```
+
+|||---|||
+
+## Use View::RemoveChildViewT<>()
+
+[`View::RemoveChildViewT<>()`](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/view.h;l=443;drc=7cba41605a8489bace83f380760486638a2a8a4a)
+**clearly conveys ownership transfer** from the parent `View` to the caller.
+Callers who wish to delete a `View` can simply ignore the return argument. This
+is preferable to calling `RemoveChildView()` and deleting the raw pointer
+(cumbersome and error-prone), calling `RemoveChildView()` without ever deleting
+the pointer (leaks the `View`), or simply deleting a pointer to a still-parented
+`View` (will work today, but is semantically incorrect and may be removed in the
+future).
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Typical code in [`network_list_view.cc`](https://source.chromium.org/chromium/chromium/src/+/master:ash/system/network/network_list_view.cc;l=296;drc=4867a6ce87c51024259259baad08b0ba8ae030a5)
+which manually deletes a child after removing it:
+
+#####
+
+**Best Practice**
+
+Rewriting using `RemoveChildViewT<>()` is shorter and safer:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+  ... if (mobile_header_view_) {
+    scroll_content()->RemoveChildView(
+        mobile_header_view_);
+    delete mobile_header_view_;
+    mobile_header_view_ = nullptr;
+    needs_relayout_ = true;
+  }
+  ...
+```
+
+#####
+
+``` cpp
+  ... if (mobile_header_view_) {
+    scroll_content()->RemoveChildViewT(
+        mobile_header_view_);
+
+    mobile_header_view_ = nullptr;
+    needs_relayout_ = true;
+  }
+  ...
+```
+
+|||---|||
+
+## Prefer Scoping Objects
+
+**Prefer scoping objects to paired Add/Remove-type calls**. For example, use
+a [`ScopedObserver<>`](https://source.chromium.org/chromium/chromium/src/+/master:base/scoped_observer.h;l=43;drc=6bd38d45dbd4144235318b607216e51a7f9dc60e)
+instead of directly calling [`View::AddObserver()`](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/view.h;l=1346;drc=7cba41605a8489bace83f380760486638a2a8a4a)
+and [`RemoveObserver()`](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/view.h;l=1347;drc=7cba41605a8489bace83f380760486638a2a8a4a).
+Such objects reduce the likelihood of use-after-free.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Typical code in [`avatar_toolbar_button.cc`](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/ui/views/profiles/avatar_toolbar_button.cc;l=50;drc=f81f0d5d17c037c5866b8808322931f313b796e1)
+that uses paired add/remove calls:
+
+#####
+
+**Best Practice**
+
+Rewriting using `ScopedObserver<>` eliminates the destructor body entirely:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+
+
+
+
+
+
+
+
+
+
+AvatarToolbarButton::AvatarToolbarButton(
+    Browser* browser, ToolbarIconContainerView* parent)
+    : browser_(browser), parent_(parent) {
+  ...
+  if (parent_)
+    parent_->AddObserver(this);
+}
+
+AvatarToolbarButton::~AvatarToolbarButton() {
+  if (parent_)
+    parent_->RemoveObserver(this);
+}
+```
+
+#####
+
+``` cpp
+class AvatarToolbarButton
+    : public ToolbarButton,
+      public ToolbarIconContainerView::Observer {
+  ...
+ private:
+  ScopedObserver<AvatarToolbarButton,
+                 ToolbarIconContainerView::Observer>
+      observer_{this};
+};
+
+AvatarToolbarButton::AvatarToolbarButton(
+    Browser* browser, ToolbarIconContainerView* parent)
+    : browser_(browser), parent_(parent) {
+  ...
+  if (parent_)
+    observer_.Add(parent_);
+}
+
+AvatarToolbarButton::~AvatarToolbarButton() = default;
+
+
+
+```
+
+|||---|||
+
+## Keep Lifetimes Fully Nested
+
+For objects you own, **destroy in the reverse order you created,** so lifetimes
+are nested rather than partially-overlapping. This can also reduce the
+likelihood of use-after-free, usually by enabling code to make simplifying
+assumptions (e.g. that an observed object always outlives `this`).
+
+|||---|||
+
+####
+
+**Avoid**
+
+Old code in `widget_interactive_uitest.cc` that destroys in the same order as
+creation:
+
+#####
+
+**Best Practice**
+
+[Current version](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/widget/widget_interactive_uitest.cc;l=492;drc=cbe5dca6cb1e1511c82776370a964d99cbf5205d)
+uses scoping objects that are simpler and safer:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+TEST_F(WidgetTestInteractive,
+       ViewFocusOnWidgetActivationChanges) {
+  Widget* widget1 = CreateTopLevelPlatformWidget();
+  ...
+
+  Widget* widget2 = CreateTopLevelPlatformWidget();
+  ...
+  widget1->CloseNow();
+  widget2->CloseNow();
+}
+```
+
+#####
+
+``` cpp
+TEST_F(WidgetTestInteractive,
+       ViewFocusOnWidgetActivationChanges) {
+  WidgetAutoclosePtr widget1(
+      CreateTopLevelPlatformWidget());
+  ...
+  WidgetAutoclosePtr widget2(
+      CreateTopLevelPlatformWidget());
+  ...
+}
+
+```
+
+|||---|||
+
+## Only Use Views Objects on the UI Thread
+
+**Always use `View`s on the main (UI) thread.** Like most Chromium code, the
+Views toolkit is [not thread-safe](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/view.h;l=170;drc=7cba41605a8489bace83f380760486638a2a8a4a).
+
+## Add Child Views in a View's Constructor
+
+In most cases, **add child `View`s in a `View`'s constructor.** From an
+ownership perspective, doing so is safe even though the `View` is not yet in a
+`Widget`; if the `View` is destroyed before ever being placed in a `Widget`, it
+will still destroy its child `View`s. Child `View`s may need to be added at
+other times (e.g. in [`AddedToWidget()`](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/view.h;l=1439;drc=7cba41605a8489bace83f380760486638a2a8a4a)
+or [`OnThemeChanged()`](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/view.h;l=1545;drc=7cba41605a8489bace83f380760486638a2a8a4a),
+if constructing the `View` requires a color; or lazily, if creation is expensive
+or a `View` is not always needed); however, do not copy any existing code that
+adds child `View`s in a [`ViewHierarchyChanged()`](https://source.chromium.org/chromium/chromium/src/+/master:ui/views/view.h;l=1422;drc=7cba41605a8489bace83f380760486638a2a8a4a)
+override, as such code is usually an artifact of misunderstanding the Views
+ownership model.
+
+|||---|||
+
+#####
+
+**Avoid**
+
+Typical code in [`native_app_window_views.cc`](https://source.chromium.org/chromium/chromium/src/+/master:extensions/components/native_app_window/native_app_window_views.cc;l=285;drc=d66100ebd950c39b80cfd1c72cec618b33eb3491)
+that sets up a child `View` in `ViewHierarchyChanged()`:
+
+#####
+
+**Best Practice**
+
+Rewriting to do this at construction/`Init()` makes |`web_view_`|'s lifetime
+easier to reason about:
+
+|||---|||
+
+|||---|||
+
+#####
+
+``` cpp
+void NativeAppWindowViews::ViewHierarchyChanged(
+    const views::ViewHierarchyChangedDetails& details) {
+  if (details.is_add && details.child == this) {
+    DCHECK(!web_view_);
+    web_view_ =
+        AddChildView(
+            std::make_unique<views::WebView>(nullptr));
+
+
+
+
+
+
+
+    web_view_->SetWebContents(
+        app_window_->web_contents());
+  }
+}
+```
+
+#####
+
+``` cpp
+
+
+NativeAppWindowViews::NativeAppWindowViews() {
+  ...
+  web_view_ =
+      AddChildView(
+          std::make_unique<views::WebView>(nullptr));
+}
+
+void NativeAppWindowViews::Init(
+    extensions::AppWindow* app_window,
+    const extensions::AppWindow::CreateParams&
+        create_params) {
+  app_window_ = app_window;
+  web_view_->SetWebContents(
+      app_window_->web_contents());
+  ...
+}
+```
+
+|||---|||
diff --git a/chromium/docs/ui/learn/index.md b/chromium/docs/ui/learn/index.md
new file mode 100644
index 00000000000..56088324791
--- /dev/null
+++ b/chromium/docs/ui/learn/index.md
@@ -0,0 +1,9 @@
+# Learning about Chromium UI
+
+# Best Practices
+
+* [Colors](bestpractices/colors.md): How to work with Chromium colors.
+* [Ownership](bestpractices/ownership.md): How to manage Views object lifetimes.
+
+# Architecture Overview
+Coming soon.
diff --git a/chromium/docs/ui/learn/navbar.md b/chromium/docs/ui/learn/navbar.md
new file mode 100644
index 00000000000..05ee5fd0943
--- /dev/null
+++ b/chromium/docs/ui/learn/navbar.md
@@ -0,0 +1,9 @@
+# Learning about Chromium UI
+
+* [Chromium Docs Home](/docs/README.md)
+* [Chromium UI](/docs/ui/index.md)
+* [Create](/docs/ui/create/index.md)
+* [Learn](/docs/ui/learn/index.md)
+* [Ask](/docs/ui/ask/index.md)
+
+[home]: /docs/ui/learn/index.md
diff --git a/chromium/docs/vscode.md b/chromium/docs/vscode.md
index 2b8eceb2c68..735e6a13dd4 100644
--- a/chromium/docs/vscode.md
+++ b/chromium/docs/vscode.md
@@ -100,7 +100,9 @@ Next, we will install some useful extensions. Jump to the extensions window
 every day:
 
 *   ***C/C++*** -
-    Code formatting, debugging, Intellisense.
+    Code formatting, debugging, Intellisense. Enables the use of clang-format
+    (via the `C_Cpp.clang_format_path` setting) and format-on-save (via the
+    `editor.formatOnSave` setting).
 *   ***Python*** -
     Linting, intellisense, code formatting, refactoring, debugging, snippets.
 *   ***Toggle Header/Source*** -
@@ -109,31 +111,25 @@ every day:
     multiple files in the workspace that have the same name.
 *   ***Protobuf support*** -
     Syntax highlighting for .proto files.
-*   ***you-complete-me*** -
-    YouCompleteMe code completion for VS Code. It works fairly well in Chromium.
+*   [***Mojom IDL support***](https://github.com/GoogleChromeLabs/mojom-language-support) -
+    Syntax highlighting and a
+    [language server](https://microsoft.github.io/language-server-protocol/)
+    for .mojom files. This isn't available on the VS Code marketplace for now.
+    You need to install it manually.
+*   ***vscode-clangd*** -
+    If you do not plan to use VSCode for debugging, vscode-clangd is a great
+    alternative to C/C++ IntelliSense. It knows about how to compile Chromium,
+    enabling it to provide smarter autocomplete than C/C++ IntelliSense as well
+    as allowing you to jump from functions to their definitions. See
+    [clangd.md](clangd.md) for setup instructions.
+    If you need to debug, disable the vscode-clangd extension, enable C/C++
+    Intellisense, and restart VSCode.
 *   ***Rewrap*** -
     Wrap lines at 80 characters with `Alt+Q`.
 *   ***Remote*** -
     Remotely connect to your workstation through SSH using your laptop. See the
     [Remote](#Remote) section for more information about how to set this up.
 
-To install You-Complete-Me, enter these commands in a terminal:
-
-```
-$ git clone https://github.com/Valloric/ycmd.git ~/.ycmd
-$ cd ~/.ycmd
-$ git submodule update --init --recursive
-$ ./build.py --clang-completer
-```
-If it fails with "Your C++ compiler does NOT fully support C++11." but you know
-you have a good compiler, hack cpp/CMakeLists.txt to set CPP11_AVAILABLE true.
-
-On Mac, replace the last command above with the following.
-
-```
-$ ./build.py --clang-completer --system-libclang
-```
-
 The following extensions might be useful for you as well:
 
 *   ***Annotator*** -
@@ -141,36 +137,23 @@ The following extensions might be useful for you as well:
 *   ***Git History (git log)*** -
     Git history view.
 *   ***chromium-codesearch*** -
-    Code search (CS) integration, see [Chromium Code
-    Search](https://cs.chromium.org/), in particular *open current line in CS*,
-    *show references* and *go to definition*. Very useful for existing code. By
-    design, won't work for code not checked in yet. Overrides default C/C++
-    functionality. Had some issues last time I tried (extensions stopped
-    working), so use with care.
+    Mac and Linux only: adds ability to open the current line in [Chromium Code
+    Search](https://cs.chromium.org/). All other functionality is deprecated, so
+    currently only of limited usefulness.
 *   ***change-case*** -
     Quickly change the case of the current selection or current word.
 *   ***Instant Markdown*** -
     Instant markdown (.md) preview in your browser as you type. This document
     was written with this extension!
-*   ***Clang-Format*** -
-    Format your code using clang-format. The C/C++ extension already supports
-    format-on-save (see `C_Cpp.clang_format_formatOnSave` setting). This
-    extension adds the ability to format a document or the current selection on
-    demand.
-*   ***vscode-clangd*** -
-    If you do not plan to use VSCode for debugging, vscode-clangd is a great
-    alternative to C/C++ IntelliSense. It knows about how to compile Chromium,
-    enabling it to provide smarter autocomplete than C/C++ IntelliSense as well
-    as allowing you to jump from functions to their definitions. See
-    [clangd.md](clangd.md) for details.
-
-    If you need to debug, disable the vscode-clangd extension, enable C/C++
-    Intellisense, and restart VSCode.
-
+*   ***you-complete-me*** -
+    Alternative autocomplete extension. Can be configured to use a variety of
+    language servers, so helpful if not using clangd for code completion.
+    See [You-Complete-Me extension setup](#You-Complete-Me-extension-setup)
+    for additional setup instructions.
 
 Also be sure to take a look at the
-[VS Code marketplace](https://marketplace.visualstudio.com/VSCode) to check out other
-useful extensions.
+[VS Code marketplace](https://marketplace.visualstudio.com/VSCode) to check out
+other useful extensions.
 
 ### Color Scheme
 Press `Ctrl+Shift+P, color, Enter` to pick a color scheme for the editor. There
@@ -271,6 +254,10 @@ $ mkdir .vscode/
 $ cp tools/vscode/settings.json5 .vscode/settings.json
 ```
 
+Note: these settings assume that the workspace folder (the root folder displayed
+in the Explorer tab) is chromium/src. If this is not the case, replace any
+references to ${workspaceFolder} with the path to chromium/src.
+
 ### Tasks
 Next, we'll tell VS Code how to compile our code and how to read warnings and
 errors from the build output. Open the file
@@ -420,6 +407,32 @@ the file path to be relative to the output dir. Check
 `gn args out/$dir --list` if `strip_absolute_paths_from_debug_symbols` is true (which is the default),
 set `cwd` to the output dir. otherwise, set `cwd` to `${workspaceRoot}`.
 
+### You-Complete-Me extension setup
+If using the You-Complete-Me extension, complete its installation by entering
+these commands in a terminal:
+
+```
+$ git clone https://github.com/Valloric/ycmd.git ~/.ycmd
+$ cd ~/.ycmd
+$ git submodule update --init --recursive
+$ ./build.py --clang-completer
+```
+If it fails with "Your C++ compiler does NOT fully support C++11." but you know
+you have a good compiler, hack cpp/CMakeLists.txt to set CPP11_AVAILABLE true.
+
+On Mac, replace the last command above with the following.
+
+```
+$ ./build.py --clang-completer --system-libclang
+```
+
+On Windows, if depot_tools' Python is the only one installed, a separate Python
+3 install is needed. The last command should then be run as follows.
+
+```
+> <Python 3 directory>/python.exe build.py --clang-completer
+```
+
 ### More
 More tips and tricks can be found
 [here](https://github.com/Microsoft/vscode-tips-and-tricks/blob/master/README.md).
diff --git a/chromium/docs/windows_build_instructions.md b/chromium/docs/windows_build_instructions.md
index 8845f8484cc..1e6628586f9 100644
--- a/chromium/docs/windows_build_instructions.md
+++ b/chromium/docs/windows_build_instructions.md
@@ -248,10 +248,13 @@ don't' set enable_nacl = false then build times may get worse.
 * `blink_symbol_level = 0` - turn off source-level debugging for
 blink to reduce build times, appropriate if you don't plan to debug blink.
 
-In order to speed up linking you can set `symbol_level = 1` - this option
-reduces the work the linker has to do but when this option is set you cannot do
-source-level debugging. Switching from `symbol_level = 2` (the default) to
-`symbol_level = 1` requires recompiling everything.
+In order to speed up linking you can set `symbol_level = 1` or
+`symbol_level = 0` - these options reduce the work the compiler and linker have
+to do. With `symbol_level = 1` the compiler emits file name and line number
+information so you can still do source-level debugging but there will be no
+local variable or type information. With `symbol_level = 0` there is no
+source-level debugging but call stacks still have function names. Changing
+`symbol_level` requires recompiling everything.
 
 In addition, Google employees should use goma, a distributed compilation system.
 Detailed information is available internally but the relevant gn arg is:
diff --git a/chromium/docs/windows_split_dll.md b/chromium/docs/windows_split_dll.md
index e8aac58cd8f..345c3e741b1 100644
--- a/chromium/docs/windows_split_dll.md
+++ b/chromium/docs/windows_split_dll.md
@@ -3,20 +3,20 @@
 A build mode where chrome.dll is split into two separate DLLs. This was
 undertaken as one possible workaround for toolchain limitations on Windows.
 
-## How
+We removed support for this again after the toolchain limitations were fixed,
+see https://crbug.com/726150.
 
-Split DLL is now default on Windows and controlled by the
-`is_multi_dll_chrome` gn variable.
+## How
 
-`is_multi_dll_chrome` applies only to chrome.dll (and not test binaries).
+Split DLL used to be controlled by the `is_multi_dll_chrome` gn variable.
 
 ## Details
 
-This forcible split is implemented by putting .lib files in either one DLL or
+This forcible split was implemented by putting .lib files in either one DLL or
 the other, and causing unresolved externals that result during linking to be
 forcibly exported from the other DLL. This works relatively cleanly for function
 import/export, however it cannot work for data export.
 
-Some more details can be found on the initial commit of the split_link script
+Some more details can be found on the initial commit of the `split_link` script
 https://src.chromium.org/viewvc/chrome?revision=200049&view=revision and the
 associated bugs: https://crbug.com/237249 https://crbug.com/237267.
diff --git a/chromium/docs/wmax_tokens.md b/chromium/docs/wmax_tokens.md
index 0fe54fe2105..5038e76b841 100644
--- a/chromium/docs/wmax_tokens.md
+++ b/chromium/docs/wmax_tokens.md
@@ -46,3 +46,12 @@ are (or were) large and widely included.
 Try using forward declarations or otherwise restructuring your change to
 avoid growing the header beyond the limit. If that is infeasible, raise the
 limit.
+
+
+## Experiences
+
+- System headers on Chrome OS differ between boards and are not covered by the
+  commit queue. This means the token limits were not tailored to those builds,
+  causing build problems downstream. To avoid this, the -Wmax-tokens warning
+  was disabled for Chrome OS (see
+  [crbug.com/1079053](https://crbug.com/1079053)).