Switching Pulpcore to Calendar Versioning scheme

Earlier today the pulpcore team decided that we want to start releasing pulpcore once per week. Some of these releases will contain features and bug fixes while others will contain only bug fixes. If we continue to use our current versioning scheme, it will be difficult to pick a ‘plugin backwards incompatible’ release that plugins can use as an upper bound in their requirements. A proposal was made to switch to Calendar Versioning[0]. That way it would be very easy to pick a pulpcore version as an upper bound that is time based. What do you all think about such a versioning scheme for pulpcore?

[0] https://calver.org/

I see no need for this. If we know that we produce at most one minor version per week, than we can still aim for compatibility until say 20 weeks in advance. And the worst thing that can happen is that we carry compatibility code around longer than that. And my personal experience is that this compatibility code is not a heavy load.

It strikes me as being awfully arbitrary to say a plugin will support core for the next X weeks/months/years.

I’d rather remove upper bounds unless there is a known breaking change, which would result in a minor release of said plugin with the introduction of an upper bounds limit.

Else, if it really is just arbitrary we are forcing work and change on admins that may not be required.

I understand this is more an argument against upper bounds than versioning :thinking:

The upper bounds are essentially pulpcore saying: “We will do our very best not to change the plugin API until version X (any changes we do plan to make will be given a deprecation warning, and only be dropped with version X)”. This is absolutely necessary to make fixing those deprecations plannable for plugins.

Apart from that, I really can’t comment on the wisdom of changing the pulpcore versioning scheme, especially without understanding the wisdom of changing to weekly releases. Except perhaps to say that it sounds like a lot of work in the plugin template in particular. It will also permanently make pulpcore less like the plugins. Or is the plan to also change the versioning for plugins? Or will pulpcore no longer use the **plugin_**template (emphasis added)?

Personally, I am pretty happy with the way things have been going (regarding the need for plugin maintenance due to changes in pulpcore or pulpcore releases). So my vote is for not changing anything. That being said, I don’t know what burdens the current system places on the pulpcore team, that make them want to change to weekly releases.

@quba42 - there are two pressures here.

One - currently, plugin-CI tests against core/main. This has led to situations where plugins released code that only worked with an unreleased version of core. We’ve added tests to deal w/ that, which result in CI runs taking significantly longer. And even when caught, it means that now a plugin has to revert such a change, if it wants to release before core gets rev’d.

To address that, we’d like to change plugin-CI to test against core-release-branches, and we’d like core to release new features more often so plugins can take advantage of them, and get support to our users more quickly.

Two - Pulp has stakeholders that want to release in a more rapid-deployment environment. If we can get releases out in a rapid cadence, we can better support that. It also lets us get our changes into the hands of a different testing environment, which would (hopefully) mean that, by the time our users who move at a more measured pace decide to upgrade, there’s been effectively more hardening along the way.

Regarding the plugin-template - we’ll def be using it, and making it even more automatic than it currently is (I think, he says, knowing he’s probably not going to be the person doing whatever work needs to happen there…) There’s been a ton of work done to make the release-process WAY more automated, which is to everyone’s benefit.

RE upper-bounds - @wibbit, @quba42 hits it right on the head. We apply the upper-bounds so that plugins can release on whatever cycle they want, knowing they don’t have to cut releases every time core does. That upper-bound is what makes discussions like this even remotely feasible :slight_smile:

Now, all of the above holds whether we move to calendar-versions or stick with semver. Whether a release is core/2023.03.01 or core/3.23.5, it’ll still do “newer” correctly, and plugins can adjust their upper-bounds as needed.

My entirely-personal opinion - I like semver, and I think it conveys useful information to our users. There’s also the very human-psychology reasoning of ‘people are more likely to accept that 3.24.5->3.24.6 is a small update, than 2023-02-27->2023-03-05 is’. But that might just be a familiarity Thing.

If we go the calendar-release route, I’d suggest YYYY-week_number-release. That would support users who won’t/can’t “upgrade” to this-week’s-release, by letting us backport fixes to previous-weekly-release, and maintain what “newer” means. So if we released this week, it’d be 2023-7-1, next week would be 2023-8-1, and if we backport a fix from 2023-8-1 it would bump last week’s branch to 2023-7-2. Or, we could do releases as 20230215-0, and bump the Y portion. There are a few options here we’d need to think on.

If we do stick w/ semver, I’d like to think hard about how far up we push the ‘Y guarantee’. We only move from 3.Y to 3.Y+1 when we add a feature or a migration to core. We’re at a point where that doesn’t happen very often. That means many/most of our weekly releases are going to be X-releases, backported onto the current-release-branch. So I’d propose more like a 10-Y guarantee - that may well carry us through the rest of the year.

As a data point - in the last 12 months, we’ve gone from releasing core/3.18 (2022-02-22) to core/3.22 (2022-12-18). I expect that pace may pick up as we add new stakeholders who want New Stuff, but I don’t expect 10 Y-releases would happen in 10 weeks.


I’m in favor of a switch because users (I believe) are users of a plugins much more than they are users of pulpcore. Yes having pulpcore use semver does have some benefits, but the downsides are more significant. By continuing to use semver if users ask “so when do I actually have to upgrade my pulpcore to continue using the plugin I care about?” the answer is: “well we really don’t know. We know it’s at least 20 weeks from now?” Same for plugin writers, “when do I actually need to release my compatibility release?” the answer is: “ummm, we’re not sure.”

By adopting calver for pulpcore (and only for pulpcore) users and plugins writers get the assurance, oh I know my next compatibility release or required pulpcore upgrade occurs in Sept '23, I can plan on that.

So yeah, +1 to calver for pulpcore.

1 Like

“End-users only really care about plugins, and plugin-authors want specificity for planning purposes” is a pretty damn compelling pair of arguments.

Building on @bmbouter’s post - what do we think about:

  • only pulpcore goes to calendar-versioning
  • versioning is YYYY.week_number.rebuild (i.e., releasing today would be 2023.7.0)
  • plugin-API guarantee is set as six(?) months? So if we started “today” and said “6 months”, the next breaking change would be 2023.33.0 (the week-of 15-AUG)

(Note - it occurs to me that we’ll need to move over the discontinuity between 3.25.0 and cal-versioning ‘carefully’, for the sake of plugin-releasers.)

I still fail to see the issue you are trying to solve with calver. Plugin writers care about two questions. Let’s assume here that we keep Pulpcore’s semver schema (major.minor.release[-dev/pre/post]) and only bump minor if there’s an entry in the feature section:

  1. When can I start using that cool brand new feature? Answer: Next weeks release.
  2. I have a deprecation warning. How long until I really need to make a compatibility release? It tells you when it’s scheduled for removal, you have at least diff in minor number of weeks.

The one thing i know for sure is that this cannot be started as an experiment. Once we switch, there is no way back.

The big takeaway I have is that we probably want to introduce new deprecations with removal schedule for the next breaking change release that is at least 3 minor versions from now. To give plugin writers some minimal amount of time to adapt.

My personal gut feeling is that the benefit is not really worth the effort of changing the pulpcore versioning (and more importantly maintaining two types of versioning in the plugin template for the rest of time). However, since I don’t have to do that work, I don’t really care that much. I am thinking of the poor pulpcore/plugin template maintainers here :stuck_out_tongue_winking_eye:.

To me, as a plugin maintainer the difference between “I need to declare compatibility up to pulpcore X, and the breaking pulpcore release will be in exactly 20 weeks (calver)” on the one hand, and “I have at least 20 weeks (semver) until the breaking pulpcore release comes along” is pretty marginal. Either way I will start paying more and more attention to deprecation warnings as the 20 weeks approach…

Also, we can still go ahead with this change if our experience of the next breaking pulpcore release ends up being a huge issue due to semver. I am not sure the cost/benefit is so obvious it makes sense to change this preemptively.

Whether it helps users plan their pulp upgrades is a separate question that I am not in a good position to answer. Do we have any feedback from users that they are finding it difficult to understand the plugin deprecation cycle or that breaking pulpcore releases have impacted them in negative ways?

1 Like

Hey folks - there was a discussion around calver and release-cadence on Fri 03-MAR. I don’t have actual “minutes”, but here are the (or some of the?) important highlights of the discussion:

attendees: ggainey, mdellweg, dkliban, bmbouter

  • RE calver: “release faster” and “change versioning-plan” are two orthogonal changes; let’s only do one at a time
    • calver change, if we decide to do it, will not happen until after 3.25 and switch-to-rapid-cadence has had a chance to settle
    • note: calver appears unlikely at this point
  • 3.25 comes out in May, w/ django-4
  • more bugfixes into latest-release
  • data-analysis of delta between feature-into-main and next-feature-into-main
  • how often do we release?
  • merge domains and release 3.23 “next week”
  • backport all bugfixes into “current release branch”
  • plugin-template changes (plugins rely on most-recent-released-core, not main) happen post-3.23

Thanks for the discussion, meeting notes, and transparency here. I have a few questions:

  • As a user, I like being able to pin to a major version of pulpcore and know that I won’t receive any major breaking changes (aside from bug fixes). I assume that goes away if pulpcore switches to calver?
  • If so, what is the protocol for knowing if I upgrade pulpcore whether I am getting breaking changes or not? I just have to look at the changelog?
  • Is the idea that plugins will still use semver?

I think I was unclear, sorry David! Lemme expand some.

First - we are unlikely to be moving to calver anytime “soon” (where 'soon" is defined roughly as “this year”). core will continue using semver for the foreseeable future.

Second - we’re going to continue to keep the no-breaking-change promise for a significant span of core-releases. We promised at the release of 3.20 that we wouldn’t make any breaking changes prior to 3.25, because we figured that would give a 6-month(ish) cadence before plugins would have to issue a new release. Starting with 3.25, “the plan” is to start releasing Y-releases much more rapidly - as often as once a week for core.

To keep a reasonable “no breaking change” promise, we’re therefore going to be extending the “Y-window” from 5 versions to more like 15-20. This should give a significant time-window (very roughly still six months(ish)) that end-users and plugins can rely on for a “compatible upper bound”.

Note that “breaking change” in this context is primarily aimed at plugin-writers. For end-users, we’re not planning on introducing breaking changes to, say, the REST API, unless we have to to fix bugs (which is always a possibility).

As you might gather from all the “(ish)”'s up there, we’re still hammering out details. We won’t be making any changes until the 3.25 release - which should as noted be in May(ish).

Does this help any?


Yes, thanks!