PatternFly 6 upgrade

If you have not previously upgraded to PatternFly 5, make sure to review its upgrade guide before attempting to support PatternFly 6, to ensure that your product has addressed any necessary changes from our previous release.

PatternFly 6 introduces new support and functionality to PatternFly, including:

• A design token system,
• A new PatternFly 6 visual theme,
• And more!

To learn about the most significant changes in this release, read our release highlights. A detailed list of all changes can be found in our major release notes.

This guide outlines the major steps you should take to upgrade your product's codebase from PatternFly 5 to PatternFly 6.

If you need support as you upgrade to PatternFly 6, the PatternFly team is here to help. Reach out to us on Slack or ask a question on our GitHub discussion board. We'll always do our best to answer your questions and connect you with the right people quickly.

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

To utilize our codemods, refer to the following instructions. You can also view the project on GitHub for additional details.

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.

To run our codemods, complete the following steps:

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

   npx @patternfly/pf-codemods@latest <path to your source code> --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:

     

   • If you see something different, please reach out before going further as there may be an issue.

2. Make note of any issues that get flagged.

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.

5. Note any errors that were not automatically fixed (some may simply be warnings) and manually repair issues that are critical.

6. Build your product.

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

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, which are outlined in our tokens documentation. As much as possible, we recommend removing your CSS overrides so that your product upgrade experience will be smoother for future releases.

If your product uses a custom solution to replicate PatternFly styling (without using PatternFly components), then it will need to be reskinned. We recognize that this may be a large undertaking, so we encourage you to reach out to the PatternFly team so that we support this work.

We offer a class-name-updater codemod to help support your updates. This utility automatically identifies class names that need to be updated as a result of class name changes in Patternfly 6, which helps highlight places in your codebase that may require you to adjust class names.

When using this codemod, keep the following guidance in mind:

• This codemod targets v5 of PatternFly by default, so you will need to add the --pfVersion 6 option if you are upgrading to v6.
• Add the --fix flag to allow the codemod to fix issues where possible.
• 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.

For more details, you can refer to the README file for this codemod.