PatternFly 5 to PatternFly 6
Following the UI plan and the component deprecations, this is the execution plan for moving Foreman from PatternFly 5 to PatternFly 6. Target release is Foreman 5.2.
5.1 branches on 2026-11-10. We will start on develop the day after. Pull requests should be open at the end of November. The coordinated merge is the week of 2026-12-08, which is still early in the 5.2 cycle.
What is already done
- PatternFly packages live in Foreman core
package.json. Plugins do not pin@patternfly/*. We will bump them in core, as agreed when we stopped using foreman-js for this. - New UI is React, PatternFly, and React Testing Library.
- Enzyme is gone from Katello and from almost every component test. It is still a core devDependency. What remains is the Jest setup, the
enzyme-to-jsonserializer,testComponentSnapshotsWithFixtures,IntegrationTestHelper(still used by foreman_rh_cloud), three core test files, andforeman_googletest setup. That tail is part of this plan, and it is the gate for React 17+.
Our React is 16.9. PatternFly 6.7 supports React 17 - 19. We will move to React 18. Because React 19 drops APIs that older libraries in our bundle still use (ReactDOM.render, findDOMNode, defaultProps on function components). React 18 is the version that unblocks PatternFly 6.
What this upgrade is
One dependency bump in Foreman core, then the PatternFly 6 upgrade applied to every repository that imports @patternfly/* or uses pf-v5- classes:
- Update
@patternfly/*to the 6.7.@patternfly/react-coregoes from 5.4 to 6.7.@patternfly/react-chartsgoes from 7.4 to 8.7, and@patternfly/react-templatesfrom 1.x to 6.7. Charts 8 has Victory and ECharts as peer dependencies. Packaging has to vendor those peers. - Dry run
npx @patternfly/pf-codemods@latest <path> --v6then verify changes and use--fix. After that,class-name-updater(pf-v5-topf-v6-),tokens-update(React tokens in JS), andcss-vars-updater(CSS variables in other files). - Remove/upgrade CSS overrides that no longer match anything - custom scss modifiers across repository.
- Review variable and class names the codemods could not map 1:1. Unmapped color tokens are rewritten to a temporary hot-pink value so they are visible.
- Check breakpoint logic. PatternFly 6 breakpoint tokens are rem, not px. A few of our own media queries are still written in px; those keep working. Anything that reads a token and compares it to a pixel value has to be updated.
Breaking changes we already know we hit:
ChipbecomesLabel(Katello errata filters, Remote Execution selected hosts).TilebecomesCard(two Katello create forms).TextbecomesContent(mostly Katello).EmptyStateis refactored, and the codemod does not cover every usage. Our shared EmptyState wrapper needs a manual pass.- Victory charts move to
@patternfly/react-charts/victory. Call sites are the core Area/Bar/Donut wrappers, Katello errata overview, Remote Execution job status, OpenSCAP, and Insights. - Button tests can fail because
aria-disabledand the text wrapper insideButtonchanged. Fixes are query changes (getByRolewithname), described in the upgrade guide.
Users should see a visual refresh from the new components: spacing, type, color, empty states, buttons. Workflows stay the same. Custom CSS aimed at pf-v5- or the old global variables will miss until we update it.
PatternFly 3, Katello Angular, and ERB pages stay on the existing roadmap. PatternFly 6 can sit next to PatternFly 3 the same way PatternFly 5 does today.
Order of work
| When | What |
|---|---|
| Nov 10–14 | Remove the remaining Enzyme usage and the dependency. Spike React 18: does the app boot, and do JS tests run on Jest 26? |
| Nov 17 | UI dev freeze starts. Open the React 18 PR on its own. |
| Nov 17–21 | Review and merge React 18, including nodejs-react and nodejs-react-dom. MountingService moves off ReactDOM.render. Testing Library moves to a release that supports React 18. |
| Nov 24–Dec 3 | PatternFly 6 - Bump dependencies in core, run codemods across plugins, fix what the codemods flag, fix tests. Open all PRs together. |
| Nov 30–Dec 4 | Maintainer review and a visual pass of the main screens. |
| Week of Dec 8 | Merge Foreman core and every plugin PR in one window. Freeze ends after that merge. |
React 18 lands first so a red test suite has one cause. PatternFly 6 PRs merge together. A plugin left behind will not build against the new packages.
If the React 18 spike shows that Jest 26 cannot run the suite, we upgrade Jest before the freeze and slide the PatternFly 6 PRs by one week. Merge then moves to the week of Dec 15.
UI dev freeze
The freeze runs from the day the React 18 PR opens until the PatternFly 6 PRs merge. About three weeks.
During the freeze, please avoid editing React and SCSS under webpack/ in core and in plugins. We will use automated tools like codemod. Ruby, API, and ERB work continues. A bugfix in a frozen file needs our cooperation, say so in the PR.
Repositories
Codemods will run on every plugin with a webpack/ tree. From current dev branch, pf-v5- shows up roughly as:
- foreman, about 350 occurrences
- katello, about 185
- foreman_remote_execution, about 50
- foreman_rh_cloud, about 30
- foreman_ansible, foreman_templates, foreman-tasks, foreman_webhooks, foreman_leapp, foreman_puppet, smaller
- foreman_openscap has charts and almost no
pf-v5-classes - foreman_discovery and foreman_google get a codemod pass; expect a small or empty diff
Please reply if your plugin imports @patternfly/* or uses pf-v5- and it is not in this list.
Custom classes across plugins also need to check and verify the usage.
How it will work
The PatternFly 6 migration is @ui_ux priorities for this release cycle. Our team will lead the migration, prepare the necessary changes across Foreman core and plugins, and coordinate testing and integration.
We will open pull requests for the affected repositories and work with their maintainers to review and merge the changes. While many updates will be automated, some will require manual adjustments and repository-specific knowledge.
Since @ui_ux does not have write access to all plugin repositories, maintainer availability and cooperation will be essential to completing the migration within the planned window.
We kindly ask maintainers to review migration PRs as early as possible and help coordinate their merges once approved. If you expect to be unavailable during the merge window, please let us know in advance so we can arrange an alternative reviewer or coordinate with another maintainer.
Our goal is to make this transition as smooth as possible while minimizing disruption to ongoing development. We appreciate everyone’s support and collaboration throughout the migration.
Packaging
Nightlies need new RPMs before the merge window. foreman-packaging today has nodejs-react 16.14.0, nodejs-patternfly-react-core 5.4.14, and nodejs-patternfly-react-charts 7.4.9. The whole nodejs-patternfly-* set moves to 6.7, charts to 8.7, plus the Victory and ECharts peers.
What we need from you
- Plugin owners/maintainers: confirm you received this message, and hold React/SCSS changes during the freeze.
- Packaging: an owner for the npm package bumps.
- Anyone who can spend a day on visual QA in December: your help will be really appreciated.
Questions and objections belong on this thread before Nov 17, when the freeze starts.