Changes that break backwards compatibility - MP 2.x or MP 3.0?

[donbo...@gmail.com]

I was reading the MicroProfile 2.0 thread (https://groups.google.com/forum/#!topic/microprofile/9hjTySQDutA) and wanted to raise a question that we all might need to consider.

We had been thinking, in MP Metrics team, that MP 2.0 would be when we make some bigger changes that aren't backwards compatible with our current API.  If MP 2.0 is just for adoption of new EE specs we would miss that opportunity.  Also if MP 2.0 is in 2Q then we likely wouldn't have time to make those proposed changes.  If we have these breaking changes in mind, should we target to make those changes in follow-on 2.1 or 2.x (x>0) minor version releases, or wait until MP 3.x?

Thanks,

Don

[Kevin Sutter]

Good questions, Don... 

Just to summarize and make sure we're all on the same page...  If MP 2.0 goes out the door as currently proposed (MP 1.x plus Java EE 8 updates for CDI, JAX-RS, JSON-P, and JSON-B), then what happens when an MP component such as Metrics needs to make a breaking API change and needs to bump up to Metrics 2.0?  Could Metrics 2.0 be included in a future MP 2.x release?  Or, would this require a version update to something like MP 3.0?

I would say the latter (require an MP 3.0 release).  Anybody using the MP 1.x or 2.x releases should expect compatibility back to the corresponding MP 1.0 or 2.0 releases, respectively.  So, if Metrics is considering an API breaking change, then they could go ahead with a Metrics 2.0 proposal and release.  But, this new Metrics 2.0 release would not be picked up by the MP convenience release until the next rev of the major release number.

Make sense?
Kevin

[Ken Finnigan]

If I'm understanding the logic, wouldn't that leads towards MP 3.0 being released, potentially, 1-2 quarters after MP 2.0.

What happens if after MP 3.0 is released with Metrics 2.0, Fault Tolerance wants to break API compatibility with it's 2.0? That means we now need an MP 4.0 doesn't it?

I'm not sure how that would be workable, as we'd potentially be releasing 2-3 MP majors every year, if specs require API breaking changes.

Should MP 2.0 be like MP 1.0, purely Java EE spec related?

It wouldn't prevent users from using individual MP specs that are 1.x on top of MP 2.0, while allowing the individual specs some time to determine whether they indeed have a need for breaking API changes?

If they don't, then they're 1.x versions can be included in MP 2.1.

If they do, then they have a chance to update to 2.x and still be part of MP 2.x

Ken

[Kevin Sutter]

Ken,
Although I agree with the idea, I can't agree with the practice.  Customers moving from MP 1.x to MP 2.0 could expect breaking API changes.  We're changing the major version.  While, customers moving from an MP 2.0 implementation to an MP 2.1 implementation would not expect breaking API changes.  So, incorporating component API breaking updates (ie. Metrics 2.0) in a subsequent MP 2.x release just doesn't seem acceptable.

So far, in the other 2.0 proposal thread, it seems that we're receiving support to provide a "Java EE 8" update only for the first release of MP 2.0.  If updates are required in a component to take advantage of the Java EE 8 updates (ie. Open API and JAX-RS 2.1), then a corresponding component update would be required in a follow-on MP 2.x release.  Depending on the extent of the changes, this might be Open API 1.1 or Open API 2.0.  But, I would consider this type of Java EE 8 exploitation as being breaking API changes.

If breaking API changes are required, then I think the major version has to be updated -- both for the component version as well as the umbrella MP version.  Otherwise, customers won't know which versions are compatible or not.

Granted, this might make for more MP releases...  But, we'll have to plan for that.  If there are several components that have breaking API changes planned, then we should consider another major release of MP.  To be honest, we should be considering breaking API changes as the exception instead of the rule.

-- Kevin

[Ken Finnigan]

I think the approach that the community wants to take with majors needs to be discussed before we're stating what the situation should be, as it has clear implications for the number of concurrent MP major versions and what is and isn't supported at any given point in time.

The original discussions around API compatibility with MP was that where possible we wanted to maintain backward compatibility, but we wouldn't stick with a broken API just because it's already there. Now to date there hasn't been much need for breaking APIs, but as the usage of MP grows I expect that it will likely change.

My concern is that we've got potentially a handful of major MP releases in a single year, making it even more confusing for users to determine what version they should be using.

Maybe each MP spec needs to spend some time determining whether they're looking to break API compatibility with a move with Java EE 8, and the release of MP 2.0 is held until any specs release those breaking changes? Otherwise in 2018 we will have MP 1.4, MP 2.0 and MP 3.0! Either creating 3 maintenance streams, or MP 2.0 becomes a one off that isn't implemented because it's out of date almost as quickly as its released.

Ken

[Kevin Sutter]

Ken,
Although I love debating this with you, I think we should wait for some input from the other MP members...  Even if you and I can come to an agreement, I'm sure sure we'll raise the hairs on somebody else...  :-)

If we're going to allow breaking API changes into subsequent MP 2.x releases, then we would have to re-define the versioning of the MicroProfile releases to correspond to the Java EE or Jakarta EE levels.  So, MicroProfile 1.x is Java EE 7, MicroProfile 2.x is Java EE 8, MicroProfile 3.x is Jakarta EE 9, and then maybe we all merge together into one happy family.  (smile) I'm not thrilled with this approach, but the alternative of having multiple major releases within a single year is daunting as well.  Or, we wait until all of the breaking API changes are figured out before cutting MicroProfile 2.0.  And, I don't think this is what the community wants.

We need to pick our poison...

-- Kevin

[Ken Finnigan]

I agree we need to have additional input from other members of the community before nailing down the scenario.

Apologies if I'm in a combative mood, I'll call it pre PTO stress ;-)

Ken

[Emily Jiang]

I think both of you have some valuable concerns.

My view is that versioning APIs should follow OSGi semantic version policy.  If there is backward incompatible changes, a major version must be increased. Otherwise, just a minor version increases.  I have already used the bnd baseline plugin to mandate some spec apis, e.g MP Config. My next task is to either create a PR or raise an issue for all specs to adopt this. This should apply to both umbrella release and each individual spec releases.

I agree with what Kevin said about MP 1.x should be backward compatible with MP 1.x-n. This complies with OSGi semantic policy.

I see Ken's points about the potential problem of maintaining two many release branches, e.g MP 1.x MP 2.x MP 3.x. I have been thinking about this same thing recently.

I think we should set a policy: per year, we should just maintain at most two parallel releases. We should set a bar on each individual specs. Each year, only one chance to break APIs. If they miss the first release of MP 2.0 or 3.0, that is. They need to workaround the problems and wait for the next turn. I think this is fair. By the way, we should be very careful when considering break backward incompatibility. We should only do it when it is absolute necessary.

Also, we should aim to move up the specs to later release branches. When we create MP 3.0, we should stablise MP 1.x.

My 2 cents.
Emily

[Alasdair Nottingham]

So from my perspective I’d like to get MicroProfile with Java EE 8 support out as soon as possible. It looks to me as if there are going to be multiple implementations of Java EE 8 relatively soon that also support MicroProfile. I think Payara is already out, and Liberty and Wildfly look pretty complete at this point. I don’t want to hold up getting Java EE 8 support so MP 2.0 can make breaking changes.

So I think this then becomes a question about what a new major version means. On the one hand it can be a marketing version, like Java EE has traditionally been, at which point we can set it to what we want whenever we want. Or it could be a semantic version at which point we should only increase the major version if we make a breaking change. 

I’m assuming (perhaps incorrectly) that CDI 2.0, JAX-RS 2.1 and JSON-P 1.1 do not make breaking changes. In which case I think the suggestion of an MP 2.0 release that bases on Java EE 8 suggests (at least to me) that we are using marketing versions. That means we could choose to make a breaking change in a MicroProfile 2.1 release if we wanted to.

In any case if we are using marketing versions I think having a 3.0 later this year isn’t an issue. 

If we intend to have semantic versions and if Java EE 8 doesn’t make breaking changes that would suggest a 1.x release. If we do that it has implications though. We couldn’t do a rev based on Java EE 7 for those runtimes that do not yet have EE 8 support.  If we intend to have semantic versions and Java EE 8 does make breaking changes then I think it shouldn’t be a problem to have an MP 3.0 later this year. I would hate to have to coordinate and limit the time people can make breaking changes to only once a year.

Personally I like the idea of semantic versions for the individual specs, I’m not so bothered by the grouping though and I would hate to delay MicroProfile with Java EE 8 at this point. I’d accept a 3.0 in 3Q in order to get MicroProfile+ EE 8 in 2Q.

My current 2 cents worth

Alasdair

--
You received this message because you are subscribed to the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/79c3d536-d065-48ea-b76c-04e27e8588f9%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Guillermo González de Agüero]

El vie., 13 abr. 2018 23:53, 'Emily Jiang' via Eclipse MicroProfile <microp...@googlegroups.com> escribió:

I think both of you have some valuable concerns.

My view is that versioning APIs should follow OSGi semantic version policy.  If there is backward incompatible changes, a major version must be increased. Otherwise, just a minor version increases.  I have already used the bnd baseline plugin to mandate some spec apis, e.g MP Config. My next task is to either create a PR or raise an issue for all specs to adopt this. This should apply to both umbrella release and each individual spec releases.

I agree with what Kevin said about MP 1.x should be backward compatible with MP 1.x-n. This complies with OSGi semantic policy.

I see Ken's points about the potential problem of maintaining two many release branches, e.g MP 1.x MP 2.x MP 3.x. I have been thinking about this same thing recently.

I think we should set a policy: per year, we should just maintain at most two parallel releases. We should set a bar on each individual specs. Each year, only one chance to break APIs. If they miss the first release of MP 2.0 or 3.0, that is. They need to workaround the problems and wait for the next turn. I think this is fair. By the way, we should be very careful when considering break backward incompatibility. We should only do it when it is absolute necessary.

+1. As Java EE users, we are used to APIs that *never* break compatibily. This is different from nearly all other software where breaking changes are expected from major releases.

Care must be taken to only break that compatibility when there are compelling reasons (an API thar proves to be broken, etc) and as you say, do it as few times as possible.

One release a year for those breaking changes sounds reasonable. Users will be confident and at the same time it doesn't put barriers to the maintainers.

--

You received this message because you are subscribed to the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/84a03cc1-570f-4b23-b401-aef5e1a29191%40googlegroups.com.

[donbo...@gmail.com]

I like the concept of semantic versions -- it makes it clear to adopters that they may need to change their code in order to move up to a newer major version.

With regards to the problem of having too many releases in rapid succession -- if we truly had the need for breaking changes in the near future we might consider giving indication that MP 2.0 is a short-term release.  That said, I don't think we're at the point that we've concluded we must have breaking changes immediately.  We need to evaluate whether the MP metrics, and other spec's breaking changes could be reasonably delayed to MP 3.0.  Teams may need to work on the current release and a future release (with breaking changes and a new Java EE level) at the same time.

I would suggest that we (MP metrics) and other component teams take a look to see when they anticipate they need to make a breaking change.  As has been mentioned a couple of times, we need to consider carefully if the changes are really justified.  This would help us understand when MP 3.0 would need to be and make this a less abstract conversation.

[Kevin Sutter]

+1, Don.  Realities do make for better conversations.  :-)  But, planning doesn't hurt either.  So, it's good to have this conversation in case it would affect the proposed MP 2.0 content and delivery.  At this point, I'm not hearing that it does and we should continue down the current path.  As these breaking API changes become more real, then we need to re-open this discussion to figure out the path going forward.

--  Kevin

[John Clingan]

Perhaps it's premature, but I'm starting to think of this in a Jakarta EE context. At some point (late this calendar year?) we are going to have to begin thinking more seriously about Jakarta EE alignment. The alignment could be philosophical (separate but aligned projects) and/or structural (MicroProfile becoming a Jakarta EE project). We're kinda in a holding pattern until Jakarta EE matures. However, I suspect that Jakarta EE is going to move more quickly than traditional Java EE. I do think we that MicroProfile is going to have to deal with major versions on a more frequent basis because of Jakarta EE. In other words, we may end up with fewer dot releases and more major releases.

I also think backwards compatibility will be impacted by this. The world just wants to move faster. Exactly how fast is going to be a learning process. Two major releases in the same year is probably too fast, though :-)

[Emily Jiang]

>Two major releases in the same year is probably too fast, though :-)

Which is why I propose we maintain two release trains per year. e.g. in 2018, we have MP 1.x and MP 2.x. In 2019, we could have MP 1.x and MP 2.x or MP2.x and MP 3.x not other patterns, I would suggest.

Thanks

Emily

--
You received this message because you are subscribed to a topic in the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/microprofile/phmKoBYLeqA/unsubscribe.
To unsubscribe from this group and all its topics, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/1903a44f-f492-45cc-a0e2-20e7e648a18c%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Thanks
Emily
=================
Emily Jiang
eji...@apache.org

[Scott Stark]

One thing we talked about during the MP hangout today was that fact that although a major release might not allow compatibility breakage, we won't prevent an implementation at a given major release level from supporting updating a particular feature to some later version. This could not be done for features like config that are in use across features, but something like metrics, jwt, etc. could be without impacting other features.

[Ondro Mihályi]

I agree with Alasdair that Java EE 8 doesn't bring breaking changes and if we want to strictly keep semantic versioning, we can include Java EE 8 features in MP 1.5 rather than MP 2.0

I think we agreed that we won't keep 2 parallel branches of MP and that after MP 2.0 there won't be any new version in the 1.x branch. That would mean that we can change the plan and turn the planned MP 2.0 into MP 1.5 that jumps to Java EE 8. For Java EE 7 platforms, MP 1.4 would be the last compatible version anyway.

Releasing MP 1.5 with Java EE 8 instad of MP 2.0 would give us some time to implement breaking changes and release them later as MP 2.0.

So I'm proposing:
 - MP 1.4 (May 2018) - the last version compatible with Java EE 7
 - MP 1.5 (Q2 2018) - MP 1.4 + Java EE 8 APIs
 - MP 2.0 (later in 2018 or 2019) - braking changes and possibly Jakarta EE 8 APIs

Also, I suggest that individual APIs also abide semantic versioning and jump to version 2.x in case of major breaking changes. That way it would be clear that the version targets MP 2.0 instead of MP 1.x. If we decide to release MP 2.0 right after MP 1.4 as we've planned then all specs should jump to 2.x version automatically and in case of breaking changes they should jump to 3.x version.

--Ondro

[alasdair....@gmail.com]

I think you have read too much into my email. I wasn't expressing an opinion about Java EE 8 causing breaking changes. I was outlining what I thought the issues for consideration were. What I said would more correctly be interpreted as:

if (semanticVersioning && ee8IsBackwardCompatible) {

   version = "1.5";

} else {

   version = "2.0";

}

I wasn't expressing a view on what the values of semanticVersioning should be or what ee8IsBackwardCompatible is. 

In terms of my view I think semanticVersioning should be used for individual specifications, but I don't think we need to for the roll up release. Not even the OSGi Alliance uses semantic versioning for the platform specification roll ups and they have been a massive advocate for semantic versioning for a long time.

Alasdair

[Emily Jiang]

https://groups.google.com/forum/#!topic/microprofile/yMt_N0KQkek please see the latest discussion there and add your comment there.

Thanks
Emily