From d9fc4fbfe30a1157d97309415a8c436467145dcf Mon Sep 17 00:00:00 2001
From: Russell Bicknell <bicknellr@google.com>
Date: Tue, 7 Apr 2020 12:06:13 -0700
Subject: [PATCH] Add `useAdoptedStyleSheetsWithBuiltCSS` section.

---
 CHANGELOG.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aafab9828e..8f8a7bd057 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,12 +2,6 @@
 
 ## Unreleased
 
-### New global behaviors
-
-#### Built Shady CSS styles automatically use constructable stylesheet objects
-
-If your application is uses pre-built Shady CSS styles and your browser supports [constructable stylesheet objects](https://wicg.github.io/construct-stylesheets/), Polymer will now extract all styles from your components' templates, join them into a single stylesheet, and share this stylesheet with all instances of the component using [`adoptedStyleSheets`](https://wicg.github.io/construct-stylesheets/#dom-documentorshadowroot-adoptedstylesheets).
-
 ### New global settings
 
 This update to Polymer includes some new [global settings](https://polymer-library.polymer-project.org/3.0/docs/devguide/settings):
@@ -167,6 +161,12 @@ This update to Polymer includes some new [global settings](https://polymer-libra
 
   **Should I use it?** This setting should only be used if startup time is significantly affected by Polymer's class initialization work - for example, if you have a large number of components being loaded but are only instantiating a small subset of them. Otherwise, this setting is **not recommended**.
 
+- `useAdoptedStyleSheetsWithBuiltCSS` / `setUseAdoptedStyleSheetsWithBuiltCSS`
+
+  **What does it do?** If your application is uses [pre-built Shady CSS styles](https://github.com/polymer/polymer-css-build) and your browser supports [constructable stylesheet objects](https://wicg.github.io/construct-stylesheets/), this setting will cause Polymer to extract all `<style>` elements from your components' templates, join them into a single stylesheet, and share this stylesheet with all instances of the component using their shadow roots' [`adoptedStyleSheets`](https://wicg.github.io/construct-stylesheets/#dom-documentorshadowroot-adoptedstylesheets) array. This setting may improve your components' memory usage and performance depending on how many instances you create and how large their style sheets are.
+
+  **Should I use it?** Consider using this setting if your app already uses pre-built Shady CSS styles. Note that position-dependent CSS selectors (e.g. containing `:nth-child()`) may become unreliable for siblings of your components styles as a result of runtime-detected browser support determining if styles are removed from your components' shadow roots.
+
 ### Other new features
 
 #### `<dom-repeat>`