From 96dcee831972dee53cc18e03a3ca6928d878186e Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Tue, 18 Feb 2025 17:00:31 -0500 Subject: [PATCH 1/6] docs(upgrade): Updates pf6 upgrade guide. --- .../content/get-started/upgrade.md | 112 ++++++++++-------- 1 file changed, 63 insertions(+), 49 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 c3086c75ee..c4c946a919 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md @@ -1,105 +1,124 @@ --- id: Upgrade source: upgrade-guide -title: PatternFly 6 upgrade +title: Upgrade to PatternFly 6 section: get-started --- import { Alert } from '@patternfly/react-core'; +import ArrowRightIcon from '@patternfly/react-icons/dist/esm/icons/arrow-right-icon'; - Make sure that you have already completed [the PatternFly 5 upgrade](https://v5-archive.patternfly.org/get-started/upgrade) before attempting to support PatternFly 6. This will ensure that your product has addressed any necessary changes from our previous release. + To ensure that your product is ready for PatternFly 6, make sure that you have first completed [the PatternFly 5 upgrade process](https://v5-archive.patternfly.org/get-started/upgrade) to address any necessary changes from our previous release. -PatternFly 6 introduces exciting new features and functionality, as described in [our release highlights](/get-started/release-highlights). To support these new offerings, we've introduced a long list of changes, the details of which can be found in [our major release notes](/get-started/upgrade/release-notes). +PatternFly 6 introduces the exciting new features and functionality outlined [our release highlights](/get-started/release-highlights). For a detailed breakdown on the work that went into this release, you can view [the PatternFly 6 major release notes](/get-started/upgrade/release-notes). -This guide outlines the steps required to upgrade your codebase to PatternFly 6 and provides additional resources to support your migration efforts. - -**Note:** If your product uses a custom solution to replicate PatternFly styling (without using PatternFly components), then it will need to be re-skinned. We recognize that this may be a large undertaking, so we encourage you to reach out to the PatternFly team so that we can help support this work. +This upgrade guide outlines the steps required to migrate your codebase to PatternFly 6 and provides additional resources to support your journey. ## Get help -If you need support as you upgrade, the PatternFly team is here to help! +If you need support as you upgrade, the PatternFly team is here to help! Since this upgrade includes significant visual changes, please contact us with questions about styles or concerns with your UI. We'll always do our best to answer your questions, double-check your work, and connect you with the right people quickly. + +[Reach out to us on Slack ](https://join.slack.com/t/patternfly/shared_invite/zt-1npmqswgk-bF2R1E2rglV8jz5DNTezMQ) -Don't hesitate to reach out to us on [Slack](https://join.slack.com/t/patternfly/shared_invite/zt-1npmqswgk-bF2R1E2rglV8jz5DNTezMQ) or ask a question on [our GitHub discussion board](https://github.com/orgs/patternfly/discussions). Since this upgrade includes significant visual changes, please contact us if you have a question about styles or if you think something looks wrong in your UI. We'll always do our best to answer your questions, double-check your work, and connect you with the right people quickly. +[Ask a question on GitHub Discussions ](https://github.com/orgs/patternfly/discussions). + +**Note:** If you use a custom solution to replicate PatternFly styling (without using PatternFly components), then your product will need to be re-skinned. This may be a large undertaking, so we encourage you to get help from the PatternFly team. ## How to upgrade -When you upgrade your product to PatternFly 6, several breaking changes will likely be introduced to your product’s codebase. These steps walk you through the migration process and connect you with resources that will help you address these breaking changes. +When you upgrade to PatternFly 6, several breaking changes will likely be introduced to your product’s codebase. + +To navigate the upgrade journey and locate helpful migration resources, follow these steps: + +1. [Run our codemods suite](#1-run-our-codemods-suite) +1. [Remove all CSS overrides](#2-remove-all-css-overrides) ### 1. Run our codemods suite -Where we can, we offer [a suite of PatternFly codemods](https://github.com/patternfly/pf-codemods/) to simplify and streamline your upgrade process. Instead of requiring you to manually identify all errors and issues in your codebase, you can run our codemods to quickly identify and fix major issues. Keep in mind that some changes will still require manual intervention, but our codemods can automatically fix a large amount of issues and flag any issues that do require manual work. +**Note:** Do this _before_ making any manual changes to your codebase. Waiting until after will lead to even more manual intervention and cleanup. -**Note:** Running codemods after making manual changes will lead to even more manual intervention and cleanup. Because of this, we strongly recommend running codemods _before_ making any manual changes to your codebase. +We offer [a suite of PatternFly codemods](https://github.com/patternfly/pf-codemods/) to simplify and streamline your upgrade process. Instead of having you manually locate errors across your codebase, our codemods can quickly identify and fix major issues. Some changes will still require manual intervention, but our codemods can automatically fix many issues and flag any that require manual work. To run our codemods, follow these steps: -1. Run the following command, adding in the path to your product's source code: +1. Run this command, adding in the path to your product's source code: `npx @patternfly/pf-codemods@latest --v6` - * You should see an output similar to running `lint`, with both a list of warnings and errors, as well as a total count of each, as shown in the following example: + * You should see an output similar to running `lint`, including a list of warnings and errors and a total count of each: ![Example codemod output.](./img/codemod-output.png) - * If you see something different, please reach out before going further as there may be an issue. + * If your results don’t look like this, [reach out to the PatternFly team](#get-help) before continuing. -2. Make note of any issues that get flagged. +2. Make note of any flagged issues. 3. Add the `--fix` flag to the end of your original command and run it again. -4. Make note of the changes applied to your product's code base. +4. Make note of the changes applied to your codebase. -5. Note any errors that were not automatically fixed (some may simply be warnings) and manually repair issues that are critical. +5. Note any errors that were not automatically fixed (some may simply be warnings) and manually repair critical issues. 6. Build your product. -7. Run codemods multiple times to ensure that all issues are flagged and addressed. +7. To ensure that all issues are flagged and addressed, complete steps 1-6 multiple times. Once everything looks correct, continue to [step 2](#2-remove-all-css-overrides). ### 2. Remove all CSS overrides -PatternFly 6 supports our new design token system, which changes variable names across PatternFly. These changes mean that **all** existing CSS overrides must be updated (or removed), because they will be targeting outdated styles and will no longer work. - -At the start of your upgrade process, we strongly recommend temporarily removing all of your CSS overrides. Once you've run through all the codemods, remove your overrides and see how things look. Since there often isn't a 1:1 equivalent for every PatternFly 5 style in PatternFly 6, your previous overrides may no longer be relevant. +The new design token system in PatternFly 6 changes variable names across PatternFly. Any existing CSS overrides will be targeting outdated styles and will no longer work, so they must be updated or removed. -We recommend *completely* removing CSS overrides as much as possible, so that your product upgrade experience will be smoother for future releases. - -If you do need to keep any CSS customizations, continue to step 3 and follow the instructions to [review and update variable and class names](#3.-review-and-update-variable-and-class-names) and make sure you are using what's most appropriate. +Once you've completed the standard codemods in step 1: +1. Temporarily remove your overrides and see how things look. + - Since there isn't a PatternFly 6 equivalent for every PatternFly 5 style, some of your previous overrides will likely have no effect and can be removed. +1. Completely remove CSS overrides as much as possible, so that your product upgrade experience will be smoother for future releases. +1. If you need to keep any CSS customizations, continue to [step 3](#3.-review-and-update-variable-and-class-names). ### 3. Review and update variable and class names -A number of variables were removed or added with PatternFly 6, primarily due to logical direction changes, refactoring, or deprecation. For more context, we've put together a list of [variables that have been removed](https://docs.google.com/spreadsheets/d/e/2PACX-1vQqeH7ThYi0jkhYEB8B2SXa7x8AaY5T9ajG6o-Ogz3p7YVp0OuTulb_L3DYLDrHlY4zUE3IBiup6tkN/pubhtml?gid=1160160856&single=true) and a list of [variables that have been added](https://docs.google.com/spreadsheets/d/e/2PACX-1vQqeH7ThYi0jkhYEB8B2SXa7x8AaY5T9ajG6o-Ogz3p7YVp0OuTulb_L3DYLDrHlY4zUE3IBiup6tkN/pubhtml?gid=268831450&single=true). -Wherever you have any custom CSS overrides that reference PatternFly class names or CSS variables, you should carefully review them and make updates to ensure that they align with our new design tokens, as described in [our tokens documentation](/tokens/all-patternfly-tokens). +A number of variables have been removed or added—primarily due to logical direction changes, refactoring, or deprecation. For more context, we've put together these lists: +- [Removed variables](https://docs.google.com/spreadsheets/d/e/2PACX-1vQqeH7ThYi0jkhYEB8B2SXa7x8AaY5T9ajG6o-Ogz3p7YVp0OuTulb_L3DYLDrHlY4zUE3IBiup6tkN/pubhtml?gid=1160160856&single=true) +- [Added variables](https://docs.google.com/spreadsheets/d/e/2PACX-1vQqeH7ThYi0jkhYEB8B2SXa7x8AaY5T9ajG6o-Ogz3p7YVp0OuTulb_L3DYLDrHlY4zUE3IBiup6tkN/pubhtml?gid=268831450&single=true). + +Wherever you have custom CSS overrides that reference PatternFly class names or CSS variables, carefully review them and make updates to ensure that they align with [our new design tokens](/tokens/all-patternfly-tokens). -To assist with naming updates, we offer 2 codemods: -- [class-name-updater](https://github.com/patternfly/pf-codemods/tree/main/packages/class-name-updater): Automatically identifies and renames classes that need to be updated as a result of changes in PatternFly 6. +To assist with naming updates, we offer 3 codemods: +1. [class-name-updater](https://github.com/patternfly/pf-codemods/tree/main/packages/class-name-updater): Automatically identifies and renames classes to align with changes in PatternFly 6. +1. [tokens-update](https://github.com/patternfly/pf-codemods?tab=readme-ov-file#tokens-update): Updates global CSS variables in your React code, including React tokens. +1. [css-vars-updater](https://github.com/patternfly/pf-codemods/tree/main/packages/css-vars-updater): Updates CSS variables in non-React files, including .css, .scss, .md, or another file type that you specify. -- [tokens-update](https://github.com/patternfly/pf-codemods?tab=readme-ov-file#tokens-update): Helps update global CSS variables in your React code. +The following guidance outlines the steps to run these codemods. #### Run class-name-updater -This utility helps highlight places in your codebase that may require you to make adjustments. Specifically, it can replace `pf-v5` prefixes with `pf-v6`. +For more details, refer to [the class-name-updater README](https://github.com/patternfly/pf-codemods/tree/main/packages/class-name-updater). -Because this utility performs a simple "find and replace" (as shown in [the README example](https://github.com/patternfly/pf-codemods/tree/main/packages/class-name-updater#example)), it's possible that it will inadvertently identify code that is formatted similarly to a PatternFly class name, but is not one. You should check to ensure that this doesn't cause any unintentional changes. +This codemod highlights places in your codebase that may require you to make adjustments and specifically replaces `pf-v5` prefixes with `pf-v6`. It performs a simple "find and replace", so it could inadvertently identify code that resembles a PatternFly class name. Keep an eye out for this to avoid any unintentional changes. When using this codemod, make sure to add: - The `--v6` option, since you are upgrading to PatternFly 6. This codemod targets v5 of PatternFly by default. - The `--fix` flag to allow the codemod to fix issues where possible. -After running the class-name-updater codemod, continue to the next step to run the tokens-update codemod using the instructions in the next section. - #### Run tokens-update -Note that this will *only* fix JavaScript or TypeScript files: not CSS. +For more details, refer to [the tokens-update example in the pf-codemods README](https://github.com/patternfly/pf-codemods?tab=readme-ov-file#tokens-update). -This codemod updates global color variables to a temporary hot pink color (`--pf-t--temp--dev--tbd`, or `t_temp_dev_tbd` when using [React tokens](/tokens/develop-with-tokens#react-tokens)) to visibly mark the places where you will have to manually replace tokens. For other global variables (like spacers, font size, or box shadows), this codemod will attempt to provide an auto-fix to match the same value (or the closest one). +This codemod updates global color variables in .js and .tsx files to a temporary hot pink color to visibly mark the places where you need to manually replace tokens (`--pf-t--temp--dev--tbd`, or `t_temp_dev_tbd` when using [React tokens](/tokens/develop-with-tokens#react-tokens)). For other global variables (like spacers, font size, or box shadows), it will attempt to provide an auto-fix to match the same or closest value. 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` +- A React token: `global_FontSize_lg` becomes `t_global_font_size_lg` + +#### Run css-vars-updater + +For more details, refer to[ the css-vars-updater README](https://github.com/patternfly/pf-codemods/tree/main/packages/css-vars-updater). + +This codemod automatically identifies PatternFly 5 CSS variables that need to be updated after the introduction of [design tokens in PatternFly 6](https://www.patternfly.org/tokens/about-tokens/). It will help you update these CSS variables in non-React files, including .css, .scss, .md, or another file type that you choose. ### 4. Update any pixel-based logic for breakpoints -In PatternFly 6, we've transitioned from using pixels to using rem units for our global breakpoint design tokens. You can find these updated values in [our tokens documentation](/tokens/all-patternfly-tokens). +PatternFly 6 uses rem units for global breakpoint [design tokens](/tokens/all-tokens), rather than pixels. -Breakpoint | Design token | Pixel value (previous) | Rem value (new) | +If you have previously implemented any breakpoint logic based on a pixel value, you will need to account for the fact that PatternFly 6 breakpoint tokens use rems. To find the rem equivalent, divide your pixel value by 16 or refer to this table: + +| Breakpoint | Design token | Pixel value (previous) | Rem value (new) | | --- | --- | --- | --- | | xs |`--pf-t--global--breakpoint--xs` | 0px | 0rem | sm |`--pf-t--global--breakpoint--sm` | 576px | 36rem @@ -108,17 +127,12 @@ Breakpoint | Design token | Pixel value (previous) | Rem value (new) | | xl |`--pf-t--global--breakpoint--xl` | 1200px | 75rem | 2xl |`--pf-t--global--breakpoint--2xl` | 1450px | 90.625rem -If you have previously implemented any breakpoint logic based on a pixel value, you will need to account for the fact that PatternFly 6 breakpoint tokens use rems. Beyond the previous table, 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: +During your upgrade, you're likely to encounter these component test failures: -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 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 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`. +| **Component** | **Error** | **Explanation** | **Solution** | +| --- | --- | --- | --- | +| Button | *Cannot find `aria-disabled`* | We changed the `isDisabled` prop to assign a value for `disabled`, but none for `aria-disabled`. Any test that looks for `aria-disabled` may fail. | | +| Button | *Cannot find button attributes when using `byText`* | We added a wrapping `div` around button text. The RTL `byText` query returns that wrapper instead of the button element itself, where button's attributes live. | Instead of `byText`, use `byRole` and pass the button text to `name`. This returns the top-level button element. | +| Select

(When using React Testing Library) | *Cannot find `role`* | The React Testing Library query can't find the menu options if the Popper menu is set to `aria-disabled` after a selection is made.

This error only seems to occur in unit tests—not browsers. | Pass in the `{hidden: true}` option.

or

Change select's `appendTo` to `inline`. | From 3ef6144ce81a79a2b9680dbcc6b4445d16e3ea20 Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Wed, 19 Feb 2025 14:46:34 -0500 Subject: [PATCH 2/6] Continue making updates --- .../content/get-started/upgrade.md | 67 +++++++++++++++---- 1 file changed, 55 insertions(+), 12 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 c4c946a919..e949d0ef44 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md @@ -4,7 +4,7 @@ source: upgrade-guide title: Upgrade to PatternFly 6 section: get-started --- -import { Alert } from '@patternfly/react-core'; +import { Alert, Button, Divider } from '@patternfly/react-core'; import ArrowRightIcon from '@patternfly/react-icons/dist/esm/icons/arrow-right-icon'; To ensure that your product is ready for PatternFly 6, make sure that you have first completed [the PatternFly 5 upgrade process](https://v5-archive.patternfly.org/get-started/upgrade) to address any necessary changes from our previous release. @@ -14,15 +14,32 @@ PatternFly 6 introduces the exciting new features and functionality outlined [ou This upgrade guide outlines the steps required to migrate your codebase to PatternFly 6 and provides additional resources to support your journey. -## Get help +## Notable changes -If you need support as you upgrade, the PatternFly team is here to help! Since this upgrade includes significant visual changes, please contact us with questions about styles or concerns with your UI. We'll always do our best to answer your questions, double-check your work, and connect you with the right people quickly. +While significant changes are mentioned in our [release highlights](/get-started/release-highlights), with detailed in our [upgrade release notes](/get-started/upgrade/release-notes), there are some changes that require manual intervention, which you should especially keep in mind as you upgrade: + +### Components + +#### Deprecated and renamed components + +1. [Chip](/components/chip): Replaced with [label](/components/label). +1. [Tile](/components/tile): Replaced with [card](components/card). +1. [Text](https://v5-archive.patternfly.org/components/text): Renamed to ["content"](/components/content). + +#### Prop changes -[Reach out to us on Slack ](https://join.slack.com/t/patternfly/shared_invite/zt-1npmqswgk-bF2R1E2rglV8jz5DNTezMQ) +1. [Expandable section](/components/expandable-section): Removed `isActive`. -[Ask a question on GitHub Discussions ](https://github.com/orgs/patternfly/discussions). +### Charts -**Note:** If you use a custom solution to replicate PatternFly styling (without using PatternFly components), then your product will need to be re-skinned. This may be a large undertaking, so we encourage you to get help from the PatternFly team. +In order to support multiple chart libraries, Victory-based charts have moved to a "victory" directory in [@patternfly/react-charts](https://www.npmjs.com/package/@patternfly/react-charts). Your import paths will need to align with this change. +- For example: `import { Area } from '@patternfly/react-charts/victory';` + +To install Victory packages, you can either: +- Install the single "victory" package to cover all features. +- Install specific packages, based on your product's features (such as "victory-core" or "victory-tooltip"). + + ## How to upgrade @@ -63,6 +80,8 @@ To run our codemods, follow these steps: 7. To ensure that all issues are flagged and addressed, complete steps 1-6 multiple times. Once everything looks correct, continue to [step 2](#2-remove-all-css-overrides). +8. You will likely need to make updates to [React tokens](https://www.patternfly.org/tokens/develop-with-tokens/#react-tokens) in your product. + ### 2. Remove all CSS overrides The new design token system in PatternFly 6 changes variable names across PatternFly. Any existing CSS overrides will be targeting outdated styles and will no longer work, so they must be updated or removed. @@ -129,10 +148,34 @@ If you have previously implemented any breakpoint logic based on a pixel value, ### Potential test failures -During your upgrade, you're likely to encounter these component test failures: +#### Button -| **Component** | **Error** | **Explanation** | **Solution** | -| --- | --- | --- | --- | -| Button | *Cannot find `aria-disabled`* | We changed the `isDisabled` prop to assign a value for `disabled`, but none for `aria-disabled`. Any test that looks for `aria-disabled` may fail. | | -| Button | *Cannot find button attributes when using `byText`* | We added a wrapping `div` around button text. The RTL `byText` query returns that wrapper instead of the button element itself, where button's attributes live. | Instead of `byText`, use `byRole` and pass the button text to `name`. This returns the top-level button element. | -| Select

(When using React Testing Library) | *Cannot find `role`* | The React Testing Library query can't find the menu options if the Popper menu is set to `aria-disabled` after a selection is made.

This error only seems to occur in unit tests—not browsers. | Pass in the `{hidden: true}` option.

or

Change select's `appendTo` to `inline`. | +1. *Cannot find aria-disabled* + - **Cause:** We changed the `isDisabled` prop to assign a value for `disabled`, but none for `aria-disabled`. + - **Fix:** Remove tests that look for `aria-disabled` in buttons. + +1. *Cannot find button attributes when using byText* + - **Cause:** We added a wrapping `div` around button text. The RTL `byText` query returns that wrapper instead of the button element itself, where button's attributes live. + - **Fix:** Instead of `byText`, use `byRole` and pass the button text to `name`. This returns the top-level button element. + +#### Select + +1. *Cannot find role* (When using React Testing Library) + - **Cause:** The React Testing Library query can't find the menu options if the Popper menu is set to `aria-disabled` after a selection is made. This error only seems to occur in unit tests—not browsers. + - **Fix:** Pass in the `{hidden: true}` option or change select's `appendTo` to `inline`. + + + +## Get help + +If you need support as you upgrade, the PatternFly team is here to help! Since this upgrade includes significant visual changes, please contact us with questions about styles or concerns with your UI. We'll always do our best to answer your questions, double-check your work, and connect you with the right people quickly. + + + + + +**Note:** If you use a custom solution to replicate PatternFly styling (without using PatternFly components), then your product will need to be re-skinned. This may be a large undertaking, so we encourage you to get help from the PatternFly team. \ No newline at end of file From b708f36f154c98dbd9abfa55da24bdf6369a1725 Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Wed, 26 Feb 2025 14:42:59 -0500 Subject: [PATCH 3/6] Continues editing and reorganizing --- .../content/get-started/upgrade.md | 66 ++++++++++++------- 1 file changed, 43 insertions(+), 23 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 e949d0ef44..a79b34b4fc 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md @@ -7,33 +7,38 @@ section: get-started import { Alert, Button, Divider } from '@patternfly/react-core'; import ArrowRightIcon from '@patternfly/react-icons/dist/esm/icons/arrow-right-icon'; - To ensure that your product is ready for PatternFly 6, make sure that you have first completed [the PatternFly 5 upgrade process](https://v5-archive.patternfly.org/get-started/upgrade) to address any necessary changes from our previous release. + To ensure your product is ready for PatternFly 6, [complete the PatternFly 5 upgrade process](https://v5-archive.patternfly.org/get-started/upgrade) first to address any necessary changes from our previous release. PatternFly 6 introduces the exciting new features and functionality outlined [our release highlights](/get-started/release-highlights). For a detailed breakdown on the work that went into this release, you can view [the PatternFly 6 major release notes](/get-started/upgrade/release-notes). -This upgrade guide outlines the steps required to migrate your codebase to PatternFly 6 and provides additional resources to support your journey. +In the following sections, this upgrade guide outlines steps required to migrate your codebase to PatternFly 6 and additional resources to support your journey: + +1. [Notable changes](#notable-changes): Significant changes you should be aware of before starting your upgrade. +1. [Upgrade steps](#how-to-upgrade): Step-by-step instructions for upgrading. +1. [Help resources](#get-help): Easy-access links to get help from the PatternFly team. + + ## Notable changes -While significant changes are mentioned in our [release highlights](/get-started/release-highlights), with detailed in our [upgrade release notes](/get-started/upgrade/release-notes), there are some changes that require manual intervention, which you should especially keep in mind as you upgrade: +Before you upgrade, familiarize yourself with these significant changes. These changes require manual intervention and you should keep them in mind as you upgrade. ### Components -#### Deprecated and renamed components - 1. [Chip](/components/chip): Replaced with [label](/components/label). 1. [Tile](/components/tile): Replaced with [card](components/card). 1. [Text](https://v5-archive.patternfly.org/components/text): Renamed to ["content"](/components/content). - -#### Prop changes - 1. [Expandable section](/components/expandable-section): Removed `isActive`. +1. [Empty state](/components/empty-state): Refactored. + - **This refactoring is not handled by codemods.** Take care and make sure to update your empty states as needed. For more details, search "empty state" in the [release notes table](/get-started/upgrade/release-notes). ### Charts -In order to support multiple chart libraries, Victory-based charts have moved to a "victory" directory in [@patternfly/react-charts](https://www.npmjs.com/package/@patternfly/react-charts). Your import paths will need to align with this change. -- For example: `import { Area } from '@patternfly/react-charts/victory';` +To support multiple chart libraries, Victory-based charts have moved to a "victory" directory in [@patternfly/react-charts](https://www.npmjs.com/package/@patternfly/react-charts). Your import paths will need to align with this change. + +- **Old path:** `import { Area } from '@patternfly/react-charts';` +- **New path:** `import { Area } from '@patternfly/react-charts/victory';` To install Victory packages, you can either: - Install the single "victory" package to cover all features. @@ -43,20 +48,23 @@ To install Victory packages, you can either: ## How to upgrade -When you upgrade to PatternFly 6, several breaking changes will likely be introduced to your product’s codebase. +Your upgrade process will require you to complete these steps: -To navigate the upgrade journey and locate helpful migration resources, follow these steps: - -1. [Run our codemods suite](#1-run-our-codemods-suite) -1. [Remove all CSS overrides](#2-remove-all-css-overrides) +1. Update your dependencies to use PatternFly 6 instead of PatternFly 5. +1. [Run our codemods suite](#1-run-our-codemods-suite). +1. [Remove all CSS overrides](#2-remove-all-css-overrides). +1. [Review and update variable and class names](). +1. [Update any pixel-based logic for your breakpoints](). ### 1. Run our codemods suite **Note:** Do this _before_ making any manual changes to your codebase. Waiting until after will lead to even more manual intervention and cleanup. -We offer [a suite of PatternFly codemods](https://github.com/patternfly/pf-codemods/) to simplify and streamline your upgrade process. Instead of having you manually locate errors across your codebase, our codemods can quickly identify and fix major issues. Some changes will still require manual intervention, but our codemods can automatically fix many issues and flag any that require manual work. +We offer a suite of PatternFly codemods to simplify and streamline your upgrade process. Instead of having you manually locate errors across your codebase, our codemods can quickly identify and fix major issues. Some changes will still require manual intervention, but our codemods can automatically fix many issues and flag any that require manual work. + +To run [our codemods](https://github.com/patternfly/pf-codemods/), follow these steps: -To run our codemods, follow these steps: +1. First, make sure that you have updated your dependencies to use PatternFly 6 instead of PatternFly 5. This is not handled by codemods. 1. Run this command, adding in the path to your product's source code: @@ -78,11 +86,23 @@ To run our codemods, follow these steps: 6. Build your product. -7. To ensure that all issues are flagged and addressed, complete steps 1-6 multiple times. Once everything looks correct, continue to [step 2](#2-remove-all-css-overrides). +7. To ensure that all issues are flagged and addressed, complete steps 1-6 multiple times. Once everything looks correct, continue to [step 3](#3-remove-all-css-overrides). + +8. You will likely need to make updates to [React tokens](https://www.patternfly.org/tokens/develop-with-tokens/#react-tokens) in your product, discussed in step 2. + +### 2. Update React tokens + +Codemods will not fix tokens imported by `@patternfly/react-tokens`. As you use codemods, you will likely receive an error that says tokens in your code don’t exist. This doesn't necessarily mean that codemods didn't work; it could mean your React tokens point to old global variables. + +Example: +- PatternFly 5 token: `global_link_Color_hover` +- PatternFly 6 token: `t_global_color_nonstatus_green_clicked` + +While these tokens have different uses, this example is meant to show how the general syntax changed, which is what leads to errors with your code. -8. You will likely need to make updates to [React tokens](https://www.patternfly.org/tokens/develop-with-tokens/#react-tokens) in your product. +There is often no 1:1 match for a PatternFly 5 and PatternFly 6 React token, so you will need to double check your code when you get this error and replace any outdated tokens with the appropriate [PatternFly 6 React token](/tokens/develop-with-tokens#react-tokens). -### 2. Remove all CSS overrides +### 3. Remove all CSS overrides The new design token system in PatternFly 6 changes variable names across PatternFly. Any existing CSS overrides will be targeting outdated styles and will no longer work, so they must be updated or removed. @@ -90,9 +110,9 @@ Once you've completed the standard codemods in step 1: 1. Temporarily remove your overrides and see how things look. - Since there isn't a PatternFly 6 equivalent for every PatternFly 5 style, some of your previous overrides will likely have no effect and can be removed. 1. Completely remove CSS overrides as much as possible, so that your product upgrade experience will be smoother for future releases. -1. If you need to keep any CSS customizations, continue to [step 3](#3.-review-and-update-variable-and-class-names). +1. If you need to keep any CSS customizations, continue to [step 4](#4.-review-and-update-variable-and-class-names). -### 3. Review and update variable and class names +### 4. Review and update variable and class names A number of variables have been removed or added—primarily due to logical direction changes, refactoring, or deprecation. For more context, we've put together these lists: - [Removed variables](https://docs.google.com/spreadsheets/d/e/2PACX-1vQqeH7ThYi0jkhYEB8B2SXa7x8AaY5T9ajG6o-Ogz3p7YVp0OuTulb_L3DYLDrHlY4zUE3IBiup6tkN/pubhtml?gid=1160160856&single=true) @@ -131,7 +151,7 @@ For more details, refer to[ the css-vars-updater README](https://github.com/patt This codemod automatically identifies PatternFly 5 CSS variables that need to be updated after the introduction of [design tokens in PatternFly 6](https://www.patternfly.org/tokens/about-tokens/). It will help you update these CSS variables in non-React files, including .css, .scss, .md, or another file type that you choose. -### 4. Update any pixel-based logic for breakpoints +### 5. Update any pixel-based logic for breakpoints PatternFly 6 uses rem units for global breakpoint [design tokens](/tokens/all-tokens), rather than pixels. From cbc86868d6da1e3cb659b35e171d7b66fdc5e72a Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Thu, 27 Feb 2025 15:28:19 -0500 Subject: [PATCH 4/6] Updates based on reviews --- .../content/get-started/upgrade.md | 23 +++++++++++-------- 1 file changed, 13 insertions(+), 10 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 a79b34b4fc..66cf58d276 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md @@ -22,7 +22,7 @@ In the following sections, this upgrade guide outlines steps required to migrate ## Notable changes -Before you upgrade, familiarize yourself with these significant changes. These changes require manual intervention and you should keep them in mind as you upgrade. +Before you upgrade, familiarize yourself with these significant changes. While some are handled by codemods, some changes *could* require manual intervention and should be kept in mind as you upgrade. ### Components @@ -31,7 +31,7 @@ Before you upgrade, familiarize yourself with these significant changes. These c 1. [Text](https://v5-archive.patternfly.org/components/text): Renamed to ["content"](/components/content). 1. [Expandable section](/components/expandable-section): Removed `isActive`. 1. [Empty state](/components/empty-state): Refactored. - - **This refactoring is not handled by codemods.** Take care and make sure to update your empty states as needed. For more details, search "empty state" in the [release notes table](/get-started/upgrade/release-notes). + - This refactoring is not *entirely* handled by codemods. Depending on your implementation, your empty states could also require manual updates. For more details, search "empty state" in the [release notes table](/get-started/upgrade/release-notes). ### Charts @@ -92,15 +92,7 @@ To run [our codemods](https://github.com/patternfly/pf-codemods/), follow these ### 2. Update React tokens -Codemods will not fix tokens imported by `@patternfly/react-tokens`. As you use codemods, you will likely receive an error that says tokens in your code don’t exist. This doesn't necessarily mean that codemods didn't work; it could mean your React tokens point to old global variables. -Example: -- PatternFly 5 token: `global_link_Color_hover` -- PatternFly 6 token: `t_global_color_nonstatus_green_clicked` - -While these tokens have different uses, this example is meant to show how the general syntax changed, which is what leads to errors with your code. - -There is often no 1:1 match for a PatternFly 5 and PatternFly 6 React token, so you will need to double check your code when you get this error and replace any outdated tokens with the appropriate [PatternFly 6 React token](/tokens/develop-with-tokens#react-tokens). ### 3. Remove all CSS overrides @@ -145,6 +137,17 @@ 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` +##### Manual React token updates +Codemods will sometimes be unable to fix *all* tokens imported by `@patternfly/react-tokens` because there is often no 1:1 match for a PatternFly 5 and PatternFly 6 React token. + +If you continually receive errors that tokens in your code don’t exist, despite re-running codemods, it doesn't necessarily mean that codemods didn't work. It could mean your React tokens point to old global variables. If so, you must locate outdated tokens and replace them with the [PatternFly 6 React token](/tokens/develop-with-tokens#react-tokens) that best fits your use case. + +Example: +- PatternFly 5 token: `global_link_Color_hover` +- PatternFly 6 token: `t_global_color_nonstatus_green_clicked` + +While these tokens have different uses, this example is meant to show how the general syntax changed, which is what leads to errors with your code. + #### Run css-vars-updater For more details, refer to[ the css-vars-updater README](https://github.com/patternfly/pf-codemods/tree/main/packages/css-vars-updater). From db312bf7d7b2abb05722a9cbc6e5d0fdb7721b02 Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Thu, 27 Feb 2025 15:30:58 -0500 Subject: [PATCH 5/6] Fix some links and headers --- .../content/get-started/upgrade.md | 20 ++++++++----------- 1 file changed, 8 insertions(+), 12 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 66cf58d276..4439b82955 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md @@ -53,8 +53,8 @@ Your upgrade process will require you to complete these steps: 1. Update your dependencies to use PatternFly 6 instead of PatternFly 5. 1. [Run our codemods suite](#1-run-our-codemods-suite). 1. [Remove all CSS overrides](#2-remove-all-css-overrides). -1. [Review and update variable and class names](). -1. [Update any pixel-based logic for your breakpoints](). +1. [Review and update variable and class names](#3-review-and-update-variable-and-class-names). +1. [Update any pixel-based logic for your breakpoints](#4-update-any-pixel-based-logic-for-breakpoints). ### 1. Run our codemods suite @@ -86,15 +86,11 @@ To run [our codemods](https://github.com/patternfly/pf-codemods/), follow these 6. Build your product. -7. To ensure that all issues are flagged and addressed, complete steps 1-6 multiple times. Once everything looks correct, continue to [step 3](#3-remove-all-css-overrides). +7. To ensure that all issues are flagged and addressed, complete steps 1-6 multiple times. Once everything looks correct, continue to [step 2](#2-remove-all-css-overrides). -8. You will likely need to make updates to [React tokens](https://www.patternfly.org/tokens/develop-with-tokens/#react-tokens) in your product, discussed in step 2. +8. You will likely need to make updates to [React tokens](https://www.patternfly.org/tokens/develop-with-tokens/#react-tokens) in your product, discussed in step 3. -### 2. Update React tokens - - - -### 3. Remove all CSS overrides +### 2. Remove all CSS overrides The new design token system in PatternFly 6 changes variable names across PatternFly. Any existing CSS overrides will be targeting outdated styles and will no longer work, so they must be updated or removed. @@ -102,9 +98,9 @@ Once you've completed the standard codemods in step 1: 1. Temporarily remove your overrides and see how things look. - Since there isn't a PatternFly 6 equivalent for every PatternFly 5 style, some of your previous overrides will likely have no effect and can be removed. 1. Completely remove CSS overrides as much as possible, so that your product upgrade experience will be smoother for future releases. -1. If you need to keep any CSS customizations, continue to [step 4](#4.-review-and-update-variable-and-class-names). +1. If you need to keep any CSS customizations, continue to [step 3](#3.-review-and-update-variable-and-class-names). -### 4. Review and update variable and class names +### 3. Review and update variable and class names A number of variables have been removed or added—primarily due to logical direction changes, refactoring, or deprecation. For more context, we've put together these lists: - [Removed variables](https://docs.google.com/spreadsheets/d/e/2PACX-1vQqeH7ThYi0jkhYEB8B2SXa7x8AaY5T9ajG6o-Ogz3p7YVp0OuTulb_L3DYLDrHlY4zUE3IBiup6tkN/pubhtml?gid=1160160856&single=true) @@ -154,7 +150,7 @@ For more details, refer to[ the css-vars-updater README](https://github.com/patt This codemod automatically identifies PatternFly 5 CSS variables that need to be updated after the introduction of [design tokens in PatternFly 6](https://www.patternfly.org/tokens/about-tokens/). It will help you update these CSS variables in non-React files, including .css, .scss, .md, or another file type that you choose. -### 5. Update any pixel-based logic for breakpoints +### 4. Update any pixel-based logic for breakpoints PatternFly 6 uses rem units for global breakpoint [design tokens](/tokens/all-tokens), rather than pixels. From e7d5acd6b6dbcfa5f3dbb9e9e01f4977a460a406 Mon Sep 17 00:00:00 2001 From: Erin Donehoo Date: Thu, 6 Mar 2025 08:39:48 -0500 Subject: [PATCH 6/6] Adds line about victory dep --- .../patternfly-docs/content/get-started/upgrade.md | 2 ++ 1 file changed, 2 insertions(+) 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 4439b82955..0f41ea045b 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/upgrade.md @@ -40,6 +40,8 @@ To support multiple chart libraries, Victory-based charts have moved to a "victo - **Old path:** `import { Area } from '@patternfly/react-charts';` - **New path:** `import { Area } from '@patternfly/react-charts/victory';` +Victory is now an optional peer dependency, allowing future chart libraries to be installed without including Victory dependencies and vice versa. + To install Victory packages, you can either: - Install the single "victory" package to cover all features. - Install specific packages, based on your product's features (such as "victory-core" or "victory-tooltip").