Breaking changes

[anbraten]

We should discuss the different types of breaking changes and the handling of those and therefore which type is causing a semver bump:

• pipeline config changes => yes / no semver bump
• setup / installation changes => yes / no semver bump

Using #2379 as a starting point for sample breaking changes.

[6543]

my take:

• pipeline config that are not extending but changing/remove things -> majour version bump
• pipeline conf that extend -> minor bump
• setup install changes with fallback -> minor bump
• setup changes that remove a fallback and/or changing/removing in a way it needs manuall action to not loose functionality -> majour bump

[anbraten]

I agree on that for the pipeline config. Each time you have to adjust your config its breaking and therefore a major. If its adding new parts (features) its minor and otherwise its a patch.

[anbraten]

How to handle deprecations?

We currently just removed deprecated options (see #2379).

Instead to remove options without breaking changes we should introduce a deprecation workflow.

It could be done by marking options / code as deprecated and removing it after a specified amount of time (we need to agree on) by:

• adding a note to the migration list in the docs
• adding a note to the changelog & release notes
• if part of the pipeline config by adding a rule to the linter Enhance linter and errors #1572
• adding a // TODO: remove deprecated option ... after 03.2024) to the code

[6543]

but if there was no version in between it, the fallback was never published ... witch it should or it's lost most of it's point to exist

[6543]

// TODO(deprecation): remove fallback after 2 releasese and alter the number by script until it reach 0 then, error and let the programmer remove it?

[anbraten]

Interesting idea. Problem with releases is that this would only make sense for a fixed release cycle. As I would like to release more often, it could easily happen that we release 2 majors in one week and therefore it would only stay for 1 week. That's why I would bind it to a time-span which in best case should start from the moment a TODO comment was released to x months.

[6543]

well that depends on #2142 ... 2 major sounds a lot to me, a agree on release more often but do minor releases

[anbraten]

Minors should not be breaking. An example if we release a feature as major and we merge a second feature and after that a bug and want to release that bug I would simply release the next major instead of backporting that bug as the feature would not be breaking and therefore we would release two majors in a shorter time.

[pat-s]

my 2 cents: a "breaking change" which requires a major version bump is actually "quite simple": whenever user/admin action is required to change something, being it a config option or something else to keep things running as before it should be part of a major version bump.

If there are just additions to features or new features that nobody could have used before, it's a minor bump.

I see many devs being "afraid" of major bumps for various reasons. IMO most of them cannot be justified. It's just a numeric number in the end "indicating something". Nobody cares if they run a software on version 1.x, 2.x or 13.x.
There shouldn't be any fears in releasing multiple major versions after each other if there is a legitimate reason for it. No different to releasing multiple minor versions.
Example projects which do this well are all the hashicorp terraform modules, e.g. https://github.com/terraform-aws-modules/terraform-aws-eks.

When releasing major versions, the changelog/upgrade notes should precisely state what actions are required to migrate to the new versions to keep everything running as it was before.

[qwerty287]

I think we decided on this: If a change is breaking, it must be in a new major. It is breaking if it requires manual actions to migrate except just downloading the new binary/image.

We can document this together with #2142, can we close this?

[anbraten]

Yes its basically discussed. Created #2383 to keep track of the ongoing deprecations.

Only thing left is an amount of time (not releases as we have no fixed schedule) deprecations have to stay before we remove them with the next major.