Skip to content

Commit

Permalink
docs(upgrade): Updates upgrade instructions. (#4348)
Browse files Browse the repository at this point in the history 
* docs(upgrade): Updates upgrade instructions.

* Adds info about variable names.

* Adjusts content and ordering

* Update get help section and edit a couple links
  • Loading branch information
@edonehoo
edonehoo authored Oct 30, 2024
1 parent d7e2d50 commit 3a8151e
Showing 1 changed file with 49 additions and 24 deletions.
73 changes: 49 additions & 24 deletions packages/documentation-site/patternfly-docs/content/get-started/upgrade.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,25 +9,29 @@ import { Alert } from '@patternfly/react-core';
<Alert variant="info" isInline title="Before you upgrade"> Make sure that you have already completed [the PatternFly 5 upgrade](https://www.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.
</Alert>

PatternFly 6 introduces exciting new features and functionality, including a visual theme refresh that's created with our new [design token system.](/tokens/about-tokens) To learn about the most significant changes in this release, read our [release highlights](/get-started/release-highlights). A detailed list of all changes can be found in our [major release notes](/get-started/upgrade/release-notes).
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).

This guide outlines the requirements for upgrading your codebase to PatternFly 6 and provides additional resources to support your migration efforts.
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.

## Get help

If you need support as you upgrade, the PatternFly team is here to help! 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). We'll always do our best to answer your questions and connect you with the right people quickly.
If you need support as you upgrade, the PatternFly team is here to help!

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.

## How to upgrade

When you upgrade your product to PatternFly 6, several breaking changes will likely be introduced to your product’s codebase.
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.

Where we can, we offer a suite of 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.
### 1. Run our codemods suite

**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.
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.

### 1. Run our codemods suite
**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.

[Our suite of PatternFly codemods](https://github.com/patternfly/pf-codemods/) will help your upgrade process. To run these codemods, follow these steps:
To run our codemods, follow these steps:

1. Run the following command, adding in the path to your product's source code:

Expand All @@ -51,38 +55,60 @@ Where we can, we offer a suite of codemods to simplify and streamline your upgra

7. Run codemods multiple times to ensure that all issues are flagged and addressed.

### 2. Review and update variable and class names
### 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.

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 token variables, as described in our [tokens documentation](/tokens/all-patternfly-tokens). As much as possible, we recommend removing your CSS overrides so that your product upgrade experience will be smoother for future releases.
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.

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.

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.
### 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-1vQQLWzMGQTAFHr6ClxoOZPpSNhP-frqu9w0DBzFJG0SOyBKKvjVV5wqz2o_Nh6jnO73oiXH259t5-V0/pubhtml?gid=673459372&single=true) and a list of [variables that have been added](https://docs.google.com/spreadsheets/d/e/2PACX-1vQQLWzMGQTAFHr6ClxoOZPpSNhP-frqu9w0DBzFJG0SOyBKKvjVV5wqz2o_Nh6jnO73oiXH259t5-V0/pubhtml?gid=0&single=true).

#### Utilize our class-name-updater codemod
[The class-name-updater codemod](https://github.com/patternfly/pf-codemods/tree/main/packages/class-name-updater) automatically identifies class names that need to be updated as a result of changes in PatternFly 6. This helps highlight places in your codebase that may require you to make adjustments.
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).

This utility performs a simple ‘find and replace’, so 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.
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.

When using this codemod, make sure to:
- Add the `--v6` option if you are upgrading to v6. This codemod targets v5 of PatternFly by default.
- Add the `--fix` flag to allow the codemod to fix issues where possible.
- [tokens-update](https://github.com/patternfly/pf-codemods?tab=readme-ov-file#tokens-update): Helps update global CSS variables in your React code.

#### Utilize our tokens-update codemod
#### 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`.

[The tokens-update codemod](https://github.com/patternfly/pf-codemods?tab=readme-ov-file#tokens-update) can help you update global CSS variables in your React code. Note that this will *only* fix JavaScript or TypeScript files: not CSS.
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.

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.

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 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
### 4. Update any pixel-based logic for breakpoints

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.
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).

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.
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
| md |`--pf-t--global--breakpoint--md` | 768px | 48rem
| lg |`--pf-t--global--breakpoint--lg` | 992px | 62rem
| 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

Expand All @@ -95,5 +121,4 @@ There are a few test failures that you're likely to encounter:
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`.

- Change select's `appendTo` to `inline`.

0 comments on commit 3a8151e

Please sign in to comment.