Breaking changes policy

[st-pasha]

I'm splitting out the discussion from #1313 for better visibility.

@st-pasha: Shouldn't we go via a more cautious deprecation route here?

@spydon: We'll release it together with other breaking changes at a later point.

So the question here is what should be the process for releasing breaking changes. The commitment that the team has made in the past doesn't have specific details:

This just means we believe the current API is stable, and we won't be making big, breaking changes that often, or without warning. Expect more structured, stable updates, especially new features.

[st-pasha]

So, the process that I've seen being very successful with other projects was the following (assume current version is 1.0.0):

1. Normally, no breaking changes are committed into the main branch. For example, you can decide to release minor versions 1.0.1, 1.0.2, etc every week -- and that won't break anyone's code.
2. New features are committed into the main branch, but they are considered experimental, in the sense that their API is allowed to change freely before the next major release. Thus, people who want to try new bleeding edge features can do so, but at their own risk.
3. When the time comes to release new major version, say 1.1.0, we search for all @Deprecated clauses that explicitly say "this feature will be removed in 1.1.0", and remove the corresponding functionality. Similarly, any feature that is marked as @ToBeDeprecated for version 1.1.0, can now be marked as simply @Deprecated.
4. Note: @ToBeDeprecated is a simple marker, it has no real effect. It might as well be replaced with a // TODO comment.

Here's why this is a good scheme:

• When in the future a developer switches to Flame 1.1.0, their code won't break. In fact, it will work exactly as before, but maybe will start emitting some deprecation warnings (easily ignorable).
• At this point, the developer knows they have ~3 months (or however long until 1.2.0) to fix those warnings. They can do so as their time permits.
• If the developers ignores the warnings and later switches to 1.2.0 -- well, now the game will break. But that would be neither sudden nor unexpected. And it will be relatively easy to fix the breakage too: all they need is to temporarily switch to 1.1.0, fix the warnings, and then upgrade to 1.2.0.

For comparison, the scheme to release all pending breaking changes at once in 1.1.0 is worse for the following reasons:

• The new features cannot be experimented with until that time. Surely, you can depend on a specific branch, but trying several new features at once is already impossible.
• When a developer switches to 1.1.0, their code will break -- suddenly and dramatically. By "dramatically" I mean with possibly hundreds of compile or runtime errors. This kind of breakage is very difficult to fix, since it requires making hundreds different changes to your code, all without the ability to test each individual change.
• Seeing hundreds different errors in your code after an upgrade may cause a panic attack :)
• The only advantage of this approach is that it allows making breaking changes to the code faster (but then, it's more of an advantage for developers than for the users).

[st-pasha]

So this scheme would have exactly those downsides that I've described: every 3 months the users code breaks without any warning.

[spydon]

They will have a warning that there will be some breaking changes every three months, and will know that we aim to release near to every new Flutter release (when they also release breaking changes). But we should still be keeping down the amount of breaking changes of course.
I don't think we have the manpower to have a complex release process like the one you describe, nobody is working full time on Flame and the time spent should be be maximized for coding in my opinion (since that is what our passion is and not driving this like a product of a for-profit company), but we can ask the rest of the team (@flame-engine/flame-colab) what they think too.

[spydon]

Btw, the first disadvantage point is not valid:

The new features cannot be experimented with until that time. Surely, you can depend on a specific branch, but trying several new features at once is already impossible.

they can depend on main to have all bleeding edge changes, just like you can use master in Flutter.

[st-pasha]

They will have a warning that there will be some breaking changes every three months

That's not much of a warning, though, is it? I mean, what can a developer do with this warning other than to dread the forthcoming release? After three month they switch to 1.1.0 and all their code is suddenly broken.

they can depend on main to have all bleeding edge changes

Sure, but that would mean having to adjust their code constantly at the most inopportune moment. People want stability, and depending on main is not stable.

I don't think we have the manpower to have a complex release process like the one you describe.

It may sound complex, but actually it's dead simple: every time a major release comes you do a code search for @Deprecated, and delete that code; then search for @ToBeDeprecated and replace with @Deprecated. This is about 10 minutes worth of work.

Compare to the scheme with stable, where you'd need to regularly cherry-pick things from one branch to another, and then somehow deal with conflicts that will inevitably arise because not every commit can be cherry-picked.

[spydon]

That's not much of a warning, though, is it? I mean, what can a developer do with this warning other than to dread the forthcoming release? After three month they switch to 1.1.0 and all their code is suddenly broken.

Sure, but the alternative is to wait 6 months to get out breaking changes.

Sure, but that would mean having to adjust their code constantly at the most inopportune moment. People want stability, and depending on main is not stable.

How do you mean that they could only depend on some new features in your proposal?

It may sound complex, but actually it's dead simple: every time a major release comes you do a code search for @Deprecated, and delete that code; then search for @ToBeDeprecated and replace with @Deprecated. This is about 10 minutes worth of work.

It only works for certain type of breaking changes though, most of our breaking changes will not be creating new methods that replace old ones, but changing the method signatures, like now in the Draggables PR.

Compare to the scheme with stable, where you'd need to regularly cherry-pick things from one branch to another, and then somehow deal with conflicts that will inevitably arise because not every commit can be cherry-picked.

I agree that this is not optimal either.