Backward compatibility strategy

[eduardolundgren]

The number of people using Metal is growing and we need a backward compatibility strategy.

The 2.x.x release have validated many aspects of the library and now it's time to be strict by introducing breaking changes without a backward compatibility plan. If a breaking change is introduced a backward compatibility plan must be provided.

Fell free to drop your suggestions or comments.

[bryceosterhaus]

Not specifically about backwards compatibility, but this is related, but I think we need start having more testing and a release-client period where the community can use and test it before an official release. Seems like immediately after releasing, we have had various small issues in which some where small api changes for consistency but would also cause breaking changes. One example of this is #137.

Also, adding additional testing via an rc period would remove some pressure from @mairatma. It seems like a lot of maintaining and pressure for a single person to handle.

Also want to note that @mairatma has done a great job thus far. So thanks for the hard work!

I can put this in a separate issue if it seems necessary

[eduardolundgren]

@bryceosterhaus We definitely will follow intermediate releases as you proposed.

The reason 2.x.x was released as final was because it's happened just after 1.x.x stable release, would be confusing to release a 2.0.0-alpha right after the 1.0.0 stable, specially because the majority of changes were on JSX.

[mairatma]

Yes, thanks a lot for the suggestion, that's a good idea. We need to start defining and formalizing these processes now.

[eduardolundgren]

What do you think about the following backwards compatibility strategy?

• A breaking change must keep the old api working as of a future version, e.g. 3.x.x.
• A sunset test group will be introduced for separating the old api test cases from the new one.
• The sunset test group will make sure that test group fails when 3.x.x version is reached.

The test case separation would help identify through the code-base what is old and what is new. Sunset test cases will be important to make sure we remove the old apis one day.

[mairatma]

I really like this sunset test idea, totally agree! Will start doing this for #137 already.

[jbalsas]

Hey guys, thanks a lot for working on this!

A couple of additional things we need to cover are:

• How often or for which motives it is reasonable for us to release a new major version thus removing old APIs and behaviours. This should help us produce somehow predictable releases and avoid quick major version jumps in the near future.
• How older versions will get support once a new major one gets released.

In the same way, the first point is related to Bryce's comment. We need to have some kind of guidelines as to when a bunch of changes can get considered a new minor version. I think a steady but controlled pace of releases will help provide stability to the framework.

[eduardolundgren]

The major changes on the library in general were very responsible, note Soy support hasn't changed, lifecycle hasn't changed, therefore all old projects (using Soy) still works on 2.x.x without any change.

• After we reach maturity in other layers, we don't intend to have any major releases that often. The JSX was experimental and it was maturing based on internal team feedback, unfortunately breaking changes were introduced.
• Support for old branches would be based on back-ports, e.g. a branch 1.x.x would exist and will receive bug-fixes that comes from master by cherry-pick or manual process.

[mairatma]

Just FYI, I've just pushed some changes that will really help this topic of backwards compatibility:

• We now have a function that can enable compatibility mode with previous versions of Metal.js. For now, when called, it just allows key to be used as ref, like it did before, so that old code with this can still work. This will be really helpful in cases where developers don't have full control of the code that needs to be changed to upgrade to 1.x and 2.x. If curious, you can take a look at 4735da0 and 6303d9c for this.
• I've created a utility function to make it easier to do the sunset tests we've talked about in this thread. You can see it here. I'm already using this to make sure that we remove the current backwards compatibility layer once we move to 3.x.

I think this is a great step into what we've been talking about here, so closing this issue now. For specific backwards compatibility requests, new issues can be opened so we discuss them better.

[yuchi]

The key to ref change is also a good testbed for codemods.

[jbalsas]

Hey @mairatma, this is wonderful news for those of us in more conservative or controlled scenarios. Thanks for making it happen!

I just have maybe a couple of comments/suggestions/petitions

Global initialization
Could we make it so it's possible to initialize the compatibility mode globally?

window.__METAL_COMPATIBILITY__ = {};

Otherwise, in amd environments we need to async require metal/src/core which may lead to unexpected execution paths. I have it running, so this is not a showstopper, but might be the cherry on top ;)

Usage warnings
Maybe we could, when in compatibility mode, show console warnings when the deprecated usages kick in. Something like:

You're using key in an unsupported way. See this url and fix this! ;)

Or, at the very least, a general warning like:

You're running in compatibility mode with the following options: ... See this url for more information

@yuchi, totally agree! The good news about this is it allows us to push new versions of metal to older platforms that cannot accept breaking changes in to existing code.

[yuchi]

@jbalsas yes and no. In DXP GA1 we have version 1.0.0-rc.19, that menas with this sunsetting policy we can get 2.x but not 3.x. Which is not bad at all. Depends on how often are releases planned to happen.

[yuchi]

But what @eduardolundgren said here:

Support for old branches would be based on back-ports, e.g. a branch 1.x.x would exist and will receive bug-fixes that comes from master by cherry-pick or manual process

is the real thing ;)

[mairatma]

@yuchi yep, we could have a codemod to help people convert later. The only problem is that key/ref are passed via soy, so it would need to affect soy files, which is I guess would be harder to make a codemod for than js.

@jbalsas Sure, we can do this, I've opened an issue for this here.

[jbalsas]

@yuchi, yeah, I thought about that, but didn't want to add more to the conversation since I figured that the sunsetting approach will be adapted based on how often we release. If we up the major version every two weeks, then that wouldn't help at all.

I totally agree with the idea of support branches, but I'm wondering how much more strain it puts on the team in contrast with a more sensible deprecation/sunsetting strategy.

[mairatma]

since I figured that the sunsetting approach will be adapted based on how often we release

Exactly :)

[zsoltbalogh]

Hi team, how do you define "breaking change"?