RFC: Sync Foreman and Katello versioning, and reset both to 5.0 with containerized deployment
Decision Due Date: 2026-07-27.
I suggest that the target for this version change be what would otherwise be Foreman 3.20. (Currently we just started the development cycle for Foreman 3.19, so 3.20 is the next cycle after that.) It’s probably good to have a decision made before stabilization week. Extrapolating out from Foreman 3.19 Schedule and Planning , “Prep week” for this current cycle starts 2026-04-27, so the corresponding point in the next cycle would be 2026-07-27.
Context and Problem Statement
What is the problem being solved?
Currently we’re planning to improve foremanctl so that it can support a complete deployment of Foreman + Katello + other plugins in a containerized, opinionated way. As far as I understand, the goal is for these changes to land no later than Foreman 3.20, hence the rationale for the Decision Due Date above.
This is a fundamental change to how these projects are packaged and deployed, and IMO this alone more than justifies a major version bump.
Secondarily, resetting both Foreman and Katello to 5.0 will also have the side benefit of resetting the “Y” version of both to 0. Aligning Foreman and Katello minor versions like this will eliminate a lot of confusion around “Which Katello goes with which Foreman version?”, etc.
How does this affect the user or developer?
I’m not fully aware of the packaging / delivery side of things and how this change will affect it, so feedback is welcome here.
Proposal
The Foreman version formerly known as 3.20 would be Foreman 5.0
The Katello version formerly known as 4.22 would be Katello 5.0
Any other plugins that wish to bump their major version number could also do so
Alternative Designs
Not incrementing the major version (e.g. remaining Foreman 3.20 and Katello 4.22): This would be introducing a breaking and/or major change without a major version bump, and would be confusing at best.
Incrementing the major version of Foreman without doing so for Katello: This would not make any sense, because then you’d have Foreman 5.0 / Katello 4.22, (or even worse, Foreman 4.0 / Katello 4.22) and we’d have all the same problems with Foreman/Katello version matching clarity that we do now.
Incrementing the major version by 1 for both projects (e.g. Foreman 4.0 / Katello 5.0): This would introduce confusion because Katello’s major version would be greater than Foreman’s, and also we’d have all the same problems with Foreman/Katello version matching clarity that we do now.
No problem on this side expected, having a clear version increase is never a problem for packaging. (Going down or changing the versioning schema would need some workarounds, but this not considered at all, so we are fine)
In my book, syncing up Katello and Foreman versions can’t come soon enough!
The fact that we need to wait for an excuse (containerized deployment) to do a major version bump first, is a shame. But now that we have that opportunity we should definitely use it to sync up those versions!
I would like that very much. And I do not mean it just as a one-time thing, but as a shift to branching the plugins together with foreman. Sadly there are plugins which are already way beyond major version 5 (the one “furthest away” is probably foreman_discovery with 26.y.z), so the proposed solution wouldn’t really work there. That being said, I don’t really have any ideas how to get out of this, beyond the crazy ones.
I’m not necessarily against this, but think it should probably be a separate proposal. It can be done apart from version bumps and doesn’t need to be simultaneous.
+1 to this, it is also a chance for us to make tough changes to the API. For example, I want to make dependency solving no longer the default for incremental update, which technically should happen in an X version (although we aren’t really following semver).
Foreman and Katello have followed the same release pattern for… forever? I see no risk here.
The monorepo idea is interesting, I suppose the benefits would mostly be on the delivery side. We’d need to talk about how repo permissions look at that point too, which could be its own debate.
Let’s sync the versions of Foreman and Katello! The earlier the better
Syncing plugin versions seems tough, e.g. in foreman_puppet we try to bump a major version on breaking changes in Foreman, so we are at 9.X at the moment.
Katello is special in that it really only works with a single version of Foreman so there is some case to be made to sync them but most plugins, like foreman_puppet, are compatible with a range of Foreman versions so it feels inappropriate to sync them. That just leads to needlessly bumping the version all the time with all the overhead associated with them.
+1 To restricting this proposal to Katello for now.
Katello version is already tightly coupled to Foreman version, just not synced up. Instead a mapping of Katello version = Foreman version N+1.N+2. Remembering this formula or mapping is a complete waste of time and head space. I for one end up consulting a “version table” roughly 5 times a day (I freely admit I am useless at learning things by heart). We should not let a discussion about other plugins derail us from syncing up Katello!
Regarding other plugins: My sense is that there won’t be quick agreement. Philosophically the whole point of plugin architectures is to offer plugin authors a degree of independence in how to handle an individual plugin. If a plugin maintainer feels the plugin is tightly coupled and should be synced up, they can do so. If a plugin maintainer feels the plugin is stable over many Foreman versions and rarely has a breaking change, there is really little reason to maintain a branch/perform a version bump for each new Foreman Y version.
The main point of this (in my mind) was for any plugins that wish to introduce breaking changes, now is a good time to do so, since Foreman and Katello both will have breaking changes as well. I agree with the posts above that we shouldn’t need to sync versions going forward for anything except Foreman + Katello.
