From 55d56db8ab9d715dce2ce4d0b4a9bf2455419c61 Mon Sep 17 00:00:00 2001
From: Erin Donehoo <edonehoo@redhat.com>
Date: Fri, 18 Oct 2024 15:43:20 -0400
Subject: [PATCH 1/2] docs(upgrade): Adds more detail to upgrade guide.

---
 packages/documentation-site/package.json       |  2 +-
 .../content/get-started/upgrade.md             | 18 ++++++++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/packages/documentation-site/package.json b/packages/documentation-site/package.json
index e84fc6d936..58b9cf8835 100644
--- a/packages/documentation-site/package.json
+++ b/packages/documentation-site/package.json
@@ -17,7 +17,7 @@
     "screenshots": "pf-docs-framework screenshots"
   },
   "dependencies": {
-    "@patternfly/documentation-framework": "6.0.0-alpha.117",
+    "@patternfly/documentation-framework": "6.0.0-alpha.118",
     "@patternfly/react-catalog-view-extension": "6.0.0-prerelease.1",
     "@patternfly/react-console": "6.0.0-prerelease.2",
     "@patternfly/react-docs": "7.0.0-prerelease.32",
diff --git a/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md b/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md
index 4310f80fb5..21034d1aeb 100644
--- a/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md
+++ b/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md
@@ -78,4 +78,22 @@ This codemod works both for CSS variables and React tokens. For example:
 - A CSS variable: `--pf-v5-global--FontSize--lg` becomes `--pf-t--global--font--size--lg`
 - A react token: `global_FontSize_lg` becomes `t_global_font_size_lg`
 
+### 3. Update any pixel-based logic
+
+In PatternFly 6, [we've transitioned from using pixels to using rem units,](/get-started/release-highlights#rem-units) which are relative units that adjust font size based on the HTML document root element size. The root size in PatternFly is 16px, meaning 16px would be 1rem, 24px would be 1.5rems, and so on. 
+
+If you have previously implemented any logic based on a pixel value, you will need to account for the fact that PatternFly 6 size and dimension tokens use rems. Dividing pixel values by 16 will give you the equivalent rem value to use.
+
+### Potential test failures
+
+There are a few test failures that you're likely to encounter: 
+
+1. **Button:** Cannot find `aria-disabled`
+    - We changed button's `isDisabled` prop to assign a value for `disabled`, but none for `aria-disabled`. As a result, any test that looks for `aria-disabled` may fail.
+1. **Button:** Cannot find `disabled` when using `byText`
+    - There's a new wrapping `div` around text in buttons. The RTL `byText` query returns that wrapper instead of the button element itself, which is where button's attributes live. Instead of `byText`, use `byRole` and pass the button text to `name`. This will return the top-level button element.
+1. **Select (when using Jest):** Cannot find `role`
+    - You may get an "unable to find role" error if the Popper menu is set to `aria-disabled` after a selection is made, because the RTL query can't find the menu options. This error only seems to occur with Jest, rather than within the browser. To resolve this, either: 
+        - Pass in the `{hidden: true}` option. 
+        - Change select's `appendTo` to `inline`.
 

From ec8af4cb4260656e7e5bf56766eb99fd2c634b95 Mon Sep 17 00:00:00 2001
From: Erin Donehoo <edonehoo@redhat.com>
Date: Fri, 18 Oct 2024 16:34:29 -0400
Subject: [PATCH 2/2] Updates from review.

---
 .../patternfly-docs/content/get-started/upgrade.md          | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md b/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md
index 21034d1aeb..98cb93eea3 100644
--- a/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md
+++ b/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md
@@ -90,10 +90,10 @@ There are a few test failures that you're likely to encounter:
 
 1. **Button:** Cannot find `aria-disabled`
     - We changed button's `isDisabled` prop to assign a value for `disabled`, but none for `aria-disabled`. As a result, any test that looks for `aria-disabled` may fail.
-1. **Button:** Cannot find `disabled` when using `byText`
+1. **Button:** Cannot find button attributes when using `byText`
     - There's a new wrapping `div` around text in buttons. The RTL `byText` query returns that wrapper instead of the button element itself, which is where button's attributes live. Instead of `byText`, use `byRole` and pass the button text to `name`. This will return the top-level button element.
-1. **Select (when using Jest):** Cannot find `role`
-    - You may get an "unable to find role" error if the Popper menu is set to `aria-disabled` after a selection is made, because the RTL query can't find the menu options. This error only seems to occur with Jest, rather than within the browser. To resolve this, either: 
+1. **Select (when using React Testing Library):** Cannot find `role`
+    - You may get an "unable to find role" error if the Popper menu is set to `aria-disabled` after a selection is made, because the React Testing Library query can't find the menu options. This error only seems to occur in unit tests, rather than within the browser. To resolve this, either: 
         - Pass in the `{hidden: true}` option. 
         - Change select's `appendTo` to `inline`.