Semantic versioning


I want to break the discussion of semver compliance off into another thread (from the versioning thread).

IMO, the big place we violate semver (and always have) is this one:

Software using Semantic Versioning MUST declare a public API. This API
could be declared in the code itself or exist strictly in documentation.
However it is done, it should be precise and comprehensive.

We’re generally careful about not changing method signatures, but there’s no clear delineation as to what’s public or private, so we usually hem and haw and make a call based on how deep the method is. Then we find out users are accessing internal methods from their own recipes or projects after release. RFC047 mentions this.

I’ll argue that we’re not breaking semver in your example. Major version bumps are for backwards incompatible changes. If a feature rewrite is intended to be backwards compatible it should not need a major version bump. If we try to reduce risk by bumping major every other release, we’ll just leave behind the users who are afraid of risk. The right way to reduce this risk is to continue to do the much harder work of improving our automated testing. A big reason we want to level up our release pipeline is to add in a more comprehensive integration/acceptance testing step.


That is terrible practice from a software development standpoint. We already don’t major bump chef often enough and can’t seem to do it more often. I would love to major version bump chef every 4-6 months and then drop support fairly aggressively, but users don’t have that kind of upgrade cycle.

So what we wind up with is that we release a major version of chef every 12-18 months, and then the window opens for major version breaking changes and we work ourselves to death trying to fix everything we can all at once, and then we push the button on the release and we have to live with the code for the next 12-18 month cycle.

And if we can’t also do aggressive changes that are intended to be backwards compatible but have some risk of introducing bugs, then what you’re really saying is we add another category of fixes that only have a 4-6 week window ever 12-18 months where they can be fixed – and where they compete with resources against all the other fixes that need to also go in that window. That would cripple the ability of the client to move forwards at all.

I also see that as being more in mold of old school stability-and-uptime-valued-over-everything-else philosophy which we’re trying to get away from. While we can argue about what DevOps and CD is or isn’t, one feature of it is that it attempts to embrace change and not block it in the name of stability. In old school IT you had an entire department which was dedicated to stability with (often) no real responsibility around the effects their policies had towards the overall velocity of the company, and the general direction we’re all heading is off into the wilderness away from that brokenness. But here you’re proposing a policy which addresses the stability of the client with no responsibility towards answering the question of how necessary, large changes happen, and its very clear to me that it’ll be repeating the same class of mistake.

And what you propose isn’t even in the SemVer spec at all. SemVer doesn’t state that you never ship refactors which cause bugs and break people. You’re just supposed to fix the bugs. That is what the minor bump is for, and what the patch bumps are for. Its only if you introduce an inherently major version breaking bug that you’re supposed to immediately revert and them bump major in order to roll forwards if that’s what you want to do.

I’d also argue that is completely impractical from the standpoint of the chef client which has a vastly larger surface than anything the SemVer spec was really meant for (libraries and web services).

And if we really stand by the letter of the SemVer law then chef-docs is our documented API and if we break you and the usage is not in chef-docs then it is NOT a major breaking change and we’re not held accountable for that. And if you want to use something and have it be reliable, you should really submit a PR against chef-docs to have it added if the usage is not documented. We actually go a lot further than that in what we consider breaking changes and if something seems ‘halfway reasonable’ to us we’ll consider it a regression and look at fixing it no matter what chef-docs does or does not say. And I think that’s probably a better world to be in than one where the chef software development treats the user needs as being inherently hostile and we get locked into a passive aggressive struggle over what is or isn’t documented in chef-docs.


I feel like maybe we drank a lot of the fast and the furious devops kool-aid inside Chef Software and figured the rest of the community was drinking it too, and maybe they haven’t all been. kool-aid poll needed.

Specifically, I felt at one point we had generally agreement that major version numbers were cheap and we could use them, but we haven’t been. I hope that as we tear down more and more of the “release ceremony” we will naturally treat version numbers as more consumable, while still supporting end-users doing semi-annual client upgrades.

chef-docs is the documented API for the DSL, but there’s PathHelper, or all the other methods we don’t expect people to be calling directly but they are.


+1, thanks for moving this off :smile:

I think that’s an excellent point. I would be glad to solve the same class of issues through additional testing, if you think that’s realistic.

I definitely don’t want to limit folks to such a short period for submitting “big” changes (whether they break compat or not). It seems like we all want to get away from that old school stability/uptime mentality, but that we’re stuck doing 12-18 month major release cycles. Maybe one of those will have to give.