Do we have some mechanism to guarantee backward compatibility of osb version?

openservicebrokerapi / servicebroker

Open Service Broker API Specification

https://openservicebrokerapi.org/

Apache License 2.0

1.19k stars 434 forks source link

Do we have some mechanism to guarantee backward compatibility of osb version? #470

Closed leonwanghui closed 6 years ago

leonwanghui commented 6 years ago

As the title shows, I didn't find any explanation on backward compatibility of osb version. But there exist some use cases about it:

Suppose the platform has integrated many external service brokers and they both support v2.12, but now the platform wants to upgrade its version to v2.13, and they are afraid that some service brokers don't work well anymore.

Would be appreciated it if someone give some answers.

duglin commented 6 years ago

As long as we're still in the v2.x range, any changes to the spec are supposed to be backwards compatible. If they're not then its a bug and we'll need to fix it.

leonwanghui commented 6 years ago

@duglin Got it, thanks. So is that what deprecated used for? And all deprecated stuffs would be removed in v3.x ?

duglin commented 6 years ago

that's the current plan, yes

leonwanghui commented 6 years ago

Ok, if so, I suggest we add some declaration (just like what you say above) in the spec about the term deprecated, so that it can be more clear for vendors to know about the version control of osb. Just my thought : )

duglin commented 6 years ago

While I think its implied by the definition of "deprecated", do you want to open a PR with some suggested text?

leonwanghui commented 6 years ago

Sure, I'm glad to have a try.

XinzhongZhou commented 6 years ago

Good issue. It means if the platform want to upgrade from V2.x to V3.x, the broker should be upgraded at the same time. But I think it is difficult to upgrade the platform and broker at the same time, because they are always developed by different company.

n3wscott commented 6 years ago

it might help to have deprecated as of 2.xx or something along those lines.

@XinzhongZhou keep in-mind that the communication between the broker and the platform contains the version the platform would like to speak, so technically to migrate from v2->v3 it would require all brokers to support v2 and v3, then switch the platform to asking for v3 protocol.

Read the API Version Header section.

XinzhongZhou commented 6 years ago

Got it, thanks. @n3wscott , Do you think it is more clear for broker developer to add some text in the API version Header section about this scenario, even though it is implied by this section?
This section only said that the broker can reject :),

n3wscott commented 6 years ago

@XinzhongZhou I think what I have suggested is a strategy for implementation, but not to be a hard rule on how you develop a broker. This is a common enough pattern that I don't see the need to detail it in this spec. OSBAPI has the hooks to make in-place upgrades work, it is up to the broker authors and platforms to make the details happen. (This is my opinion, @duglin or anyone else feel free to disagree)

leonwanghui commented 6 years ago

@duglin @n3wscott Hi, I have checked the release notes and it turns out the 2.1 was released 4 years ago, so does that mean we need to keep it compatible of over 4 years work? If so, I think we have a lot of bugs to be fixed as long as we compare 2.13 with 2.1 : )

Any thoughts?

duglin commented 6 years ago

@leonwanghui that's the intent - ignoring any changes that were made due to clarifications and bugs. If you know of some things that have broken it might be good to enumerate them someplace (aside from the release notes) so that 1) we can agree that it was intentional, and 2) its easy for someone to find all of them.

leonwanghui commented 6 years ago

Yeah I agree, but it seems to extend to another question that when is next enabling-deprecated release (3.x) to be published, which is also concerned by both platforms and service broker providers. Or do we have the general plan of next one or two big releases?

mattmcneeney commented 6 years ago

This raises the question of what happens when v3 is released? My guess is that Platforms would support both v2 and v3, and would likely 'try' v3 first, and then revert to v2 if the broker rejected the request. But is that the ideal workflow? Why not allow brokers to advertise the versions of the spec they support?

n3wscott commented 6 years ago

version negotiation sounds like a good plan.

leonwanghui commented 6 years ago

Sorry for the long-time delay, I know it's a tough battle to keep version compatible, and actually I don't have any proposed solution for solving this problem. So I'm gonna close this issue, for now.

But personally for tracking any patch with compatibility impact, I suggest we can mark these patches with specific tag (such like needs-backward-compatible).