SemVer instead of `configVersion` for breaking changes

[M4t7e]

What would you like?

First of all, thank you for this awesome project! 🙂

I noticed that configVersion is used to track breaking changes, which means users need to keep track of both the Helm chart version and configVersion.

I’d like to suggest switching to the SemVer scheme and bumping the major version for breaking changes, rather than using configVersion. This approach aligns with the de facto standard most people are familiar with and works well with dependency management tools like Renovate.

Contributing

Vote on this issue by adding a 👍 reaction.
To contribute a fix for this issue, leave a comment (and link to your pull request, if you've opened one already).

[aureq]

@M4t7e Thank you for the report. I understand SemVer, but the point of configVersion is to purposefully stop a deployment if someone hasn't 1) upgraded their values and 2) changed to the required configVersion so the current running version keeps running.

Do you mind explaining how to implement a gating mechanism that would help prevent blind upgrades from breaking an already deployed webhook when some breaking changes in the configuration are introduced please?

[M4t7e]

Typically, this is not handled separately, since a major version bump in SemVer clearly signals breaking changes. This is actually the gate. It is up to the user to review the changes and update their configuration accordingly. If users blindly upgrade across major versions, it is expected that things might break due to incompatible configs, and this is standard for software following SemVer:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes

Additionally, most dependency management tools (like Renovate) understand SemVer rules. They won’t automatically apply major version upgrades without explicit approval/configuration from the user, which helps prevent accidental breaking changes during upgrades.

I understand the intention is to protect users from breaking changes, but this concern is already addressed by the SemVer versioning scheme. If a user ignores major version bumps and blindly upgrades software, it will eventually break. This is the case for almost every software.

[aureq]

@M4t7e In what way configVersion is causing friction in the way you use this Helm Chart? Is it breaking something? Or is it something else?

[soupglasses]

I think the friction comes from that you cannot trust the chart version to signify breaking changes.

This is handy when used inside of tooling like Renovate, where you can define different actions based on if the version update is a patch, minor or major change.

Where configVersion can blow up is if you configure renovate to auto-merge helm chart updates on minor and patch levels, and only open a pull request for major version changes.

So the configVersion would require custom logic to parse out, but a larger issue is how to clearly find the new configVersion. I am unsure if you can find this in a way which Renovate would be happy with. Since the issues would only show up at runtime, and you can't easily pull out the newer configVersion in Renovate.

Even if you do not configure something like Renovate, not being able to trust that updating from 0.8.0 to 0.9.0 will not cause breaking changes (as guaranteed by semver conventions), you will need to manually look up a values.yaml each time to find the "real" version stored inside configVersion.

So if you start doing SemVer for the chart releases to help alleviate this, then there would also be little reason to keep the current configVersion around. I could see good reason to keep configVersion around if you always supported previous versions in all newer versions of the chart. But as you currently describe it, it would be better to let it fail and use SemVer instead over the custom logic.

[aureq]

I see what you're saying @soupglasses however, how do I support people who don't seem to understand semver and open bugs requesting support where in fact they didn't notice the version bump and indeed the breaking changes? Any suggestions would be welcome.

[aureq]

@soupglasses @M4t7e Thank you for your patience regarding this issue. The option configVersion will likely disappear very soon as I'm currently writing the schema for values.yaml. That schema should provide strong guardrails to users when editing their deployment settings.