From 5a70531d985cd0ac450564c472b98f853eb0bf7e Mon Sep 17 00:00:00 2001
From: Dmitry Gozman <dgozman@gmail.com>
Date: Mon, 11 Nov 2024 15:25:57 +0000
Subject: [PATCH] docs: update release notes for headless

---
 docs/src/browsers.md         |  4 +--
 docs/src/release-notes-js.md | 51 +++++-------------------------------
 2 files changed, 9 insertions(+), 46 deletions(-)

diff --git a/docs/src/browsers.md b/docs/src/browsers.md
index 52b3272096..c47aef4303 100644
--- a/docs/src/browsers.md
+++ b/docs/src/browsers.md
@@ -474,9 +474,9 @@ Google Chrome and Microsoft Edge respect enterprise policies, which include limi
 
 ### Chromium Headless Shell
 
-Playwright runs a regular Chromium build in headed and headless modes. Note that headless mode has changed in Playwright version 1.49 when Chromium entirely switched to the [new headless implementation](https://developer.chrome.com/docs/chromium/headless).
+Playwright runs a regular Chromium build in headed and headless modes. Note that headless mode has changed in Playwright version 1.49, see #x for details.
 
-Playwright also provides [`'chromium-headless-shell'` channel](https://developer.chrome.com/blog/chrome-headless-shell) that differs from the regular Chromium browser in features, performance and behavior. If you would like to optimize your CI performance and can tolerate different behavior in some cases, install and use this channel similarly to [Google Chrome & Microsoft Edge](#google-chrome--microsoft-edge).
+Playwright also provides [`'chromium-headless-shell'` channel](https://developer.chrome.com/blog/chrome-headless-shell) that differs from the regular Chromium browser in features, performance and behavior. If you would like to optimize your CI performance and can tolerate different behavior in some cases, install and use this channel similarly to [Google Chrome and Microsoft Edge channels](#google-chrome--microsoft-edge).
 
 ### Firefox
 
diff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.md
index 6919b661a3..a79604c675 100644
--- a/docs/src/release-notes-js.md
+++ b/docs/src/release-notes-js.md
@@ -8,53 +8,16 @@ import LiteYouTube from '@site/src/components/LiteYouTube';
 
 ## Version 1.49
 
-### New Chromium Headless
+### Breaking: New Chromium Headless
 
-Prior to this release, Playwright was running the old established implementation of Chromium headless. However, Chromium had entirely switched to the [new headless mode](https://developer.chrome.com/docs/chromium/headless) implementation, so Playwright had to switch as well.
+Playwright is switching to the new headless mode in Chromium. Please see #x for details.
 
-Most likely, this change should go unnoticed for you. However, the new headless implementation differs in a number of ways, for example when handling pdf documents, so please file an issue if you encounter a problem.
+Short summary:
+- Old headless mode is removed, Playwright switches to new headless mode.
+- You will have to update your test suite accordingly, for example with new screenshot expectations.
+- You can temporary opt-out by using `chromium-headless-shell` channel.
 
-### Chromium Headless Shell
-
-Playwright now also ships `chromium-headless-shell` channel that is a separate build that closely follows the old headless implementation. If you would like to keep the old behavior before you are ready to switch to the new headless, please fallback to this channel:
-
-1. First, install this channel prior to running tests. Make sure to list all browsers that you use.
-
-  ```bash
-  # running tests in all three browsers, headless and headed
-  npx playwright install chromium chromium-headless-shell firefox webkit
-
-  # running tests in all three browsers on CI, headless only
-  npx playwright install chromium-headless-shell firefox webkit
-  ```
-
-1. Update your config file to specify `'chromium-headless-shell'` channel.
-
-  ```js
-  import { defineConfig, devices } from '@playwright/test';
-
-  export default defineConfig({
-    projects: [
-      {
-        name: 'chromium',
-        use: {
-          ...devices['Desktop Chrome'],
-          channel: 'chromium-headless-shell',
-        },
-      },
-      {
-        name: 'firefox',
-        use: { ...devices['Desktop Firefox'] },
-      },
-      {
-        name: 'webkit',
-        use: { ...devices['Desktop Safari'] },
-      },
-    ],
-  });
-  ```
-
-1. Note that `chromium-headless-shell` channel only supports headless operations. If you try to run tests in headed mode, it will automatically fallback to regular `chromium`.
+Please read #x for in-depth explanation.
 
 ### Browser Versions