Update of versioning guidelines for the url field #405
Comments
|
I'd be interested to know if anybody is using the current alpha or release candidate URL rules in their test implementations. It complicates testing as every alpha or RC bump, even for minor documentation updates, requires the clients to be updated at the same time. If nobody is using the URL naming rules for alpha and release candidate in practice, and they are only used in the documentation, why not just use the "public" URL naming rules in all versions of the YAML? It would be one less thing to get wrong. The YAML anyway has the true version number in it. |
|
Hi, From my undestanding of current Release Management Guidelines the below scenarios would generate a newer release candidate, that is: version: 0.3.1-rc.1 gives url: .../v0.3rc1; but also: v0.3.2-rc.1 would give url: .../v0.3rc1
version 1.1.0-alpha.1 gives url: .../v1alpha1; but also: v1.1.1-alpha.1 would give url: .../v1alpha1 Having the same "minor" version it implies no functionality change (descriptive information adaptation), so managing it as a new release candiadte should be enough (imo) and also in may cases some that can be adjusted in the Public release version |
Hi @PedroDiez ... I agree with your proposal, this was also my first idea to handle these situations. Have added it in the issue description as alternative solution. Actually my favorite, as it is nearer to the intention of semantic versioning. |
My view: The intention of having different server URLs within the alpha and release candidate versions is to safely differentiate them from the URLs in production (assuming that these version are only used in test and lab deployments the impact on test clients should be limited). Alpha and release candidates could (e.g. unintentionally) contain breaking changes, one of the purposes of these releases is to exactly find such bugs. Saying this, there can be also breaking changes between different release candidates (e.g. after reverting an unintentionally breaking change), so they should have different server URLs. |
Hi Pedro, the reason why I prefered to just put the full version number is that I am afraid that such continuous numbering across releases may 1) be hard to explain and 2) will lead to many mistakes. So the simplest IMHO is to just include the full version in the url of alpha and rc APIs, as they are anyway only used for dev and testing, and makes it fully unambiguous. Already with the current rule we encounter a lot of mistakes when reviewing the APIs. |
Sure - but my question was "is anyone actually doing it this way?". Anyone using a common API root for production and non-production APIs is just asking for trouble. Breaking changes in alphas or RCs indeed require client implementations to be updated. My point was that, with the current system, non-breaking changes also require ALL client implementations to be updated. |
IMHO most likely the apiRoots will be different, but even so I think we still want to be able to identify which OAS spec was used by looking at the URL, especially during testing, in case of testing multiple versions in parallel (maybe that is unlikely, especially if client and server are not owned by the same team. |
|
I conclude this discussion as follows: adoption of using the full version (including extensions) in the servers.url field of alpha and release-candidate APIs to avoid numbering clashes. It is recognized that test clients will need to be adapted, but this is deemed acceptable as it has the advantage of uniquely identifying the version in a dev or test environment where changes can happen rapidly and especially useful when the client and the server are owned by different teams and they may not have the YAML at hand. Actions:
|
Problem description
There is an issue with the current versioning rules for the version in the url field in the OAS for alpha and release-candidate versions.
Today, for patch versions and minor updates,of versions x.y.z with x>0, when shortening the version there is a risk of clashes of the shortened version across releases.
For example, with the current rules:
Expected behavior
The intent of extending the version in the url with the alpha and rc information was meant to enable draft implementations for API testing to make sure the API is well identified. However, the current rules are not sufficient to distinguish all cases.
Propose solution:
Update the versioning guidelines to state that the version in the url for alpha and release candidate version should include the complete version.
The updated table is as follows:
The proposal is to
As this applies only during API development phase in CAMARA before public release, it should not be a problem.
We would like to get the opinion of the Commonalities team, and understand if anyone has encountered this issue and knows of alternative solutions.
The current proposal seemed to be the easiest to explain to the API developers.
Alternative solution (added by @hdamker)
An alternative solution would be to keep the current rules, but bump the number of a new alpha and release candidate version as long as an alpha or release candidate for the same major version (or minor version in case of 0.x). So, as described within @PedroDiez comment below.
The text was updated successfully, but these errors were encountered: