Frozen versions of WES spec

[susheel]

To provide backward compatibility support WES servers/clients, we need to provide a frozen-in-time version of the spec. Suggest we keep a major-minor-version in the /openapi folder for the repo locked for any further edits.

WES v1 --> /openapi/v1/workflow_execution_service.swagger.yaml WES latest --> /openapi/workflow_execution_service.swagger.yaml

OR

WES v1 --> /openapi/workflow_execution_service.v1.swagger.yaml WES latest --> /openapi/workflow_execution_service.swagger.yaml

P.S. I would also suggest dropping swagger from the specification filename

[jaeddy]

I like the first option. When you say major-minor, do you mean there might be a /openapi/v1.1/workflow_execution_service.swagger.yaml as well?

I have no objections to dropping swagger from the filename. Is there any convention or standard we should follow?

[susheel]

I don't think there is a convention. I was suggesting v1 and v1.1, but happy to limit to just major releases.

[geoffjentry]

IMO the general convention is vMAJOR, not vMAJOR.MINOR in the URL

[susheel]

Happy with vMAJOR

[jaeddy]

Sounds good. @susheel, can you make a PR for this?

[juhtornr]

I think that we should fix #139 before freezing the spec.

[ruchim]

@susheel -- sorry to get to this so late -- does https://github.com/ga4gh/workflow-execution-service-schemas/blob/develop/openapi/workflow_execution_service.openapi.yaml#L5 solve the spirit of this request -- that we track major/minor version along with the exact definition of that spec?

[vinjana]

Not sure whether I should open a new issue or just add my comments here. I'll do the latter.

There is this "freeze" request by @susheel . Could he maybe meant that there should be a tag for the 1.0.1 version? This is actually what I would really like to have before implementing this version in our WES. The 1.0.1 version is already deployed as reference documentation -- so I think it is quite official -- but I do not know the exact commit. Maybe it is possible to find some commit that contains exactly the deployed 1.0.1 version and just add a tag to it?

Generally, in terms of governance, I think as a standard it would be appropriate to have a defined release process -- at least concerning the technical side. In my projects, I made good experiences with releasing via commits and configuring my CD such that only correctly tagged versions (e.g. matching a tag pattern) are being deployed. E.g. such tags may be automatically deployed to the reference documentation site.

Finally as a supplement to the discussion about major/minor versions above: I suggest to use Semantic Versioning 2 for the API spec. It seems like you tried to do s.th. like that -- because you have these three component version numbers. However, from 1.0.0 to 1.0.1 new fields were added in the ServiceInfo, and, AFAIK, this should then better released with a minor version bump. My understanding of semantic versioning is that a major version would not be backwards compatible (e.g. remove fields from responses), a minor version would add features to the API (e.g. add fields to responses), and a patch version would just make small corrections that do not add features nor modify the behavior of the existing spec.

~~Note that with this interpretation, it would be important to include the minor version into the route. For strict client API implementations it would make a difference, because such a client may check whether a response has additional unexpected fields. On the other hand, an implementation of the 1.1.x version may rely on these new fields to be present. Therefore, unless you want to make major releases when adding fields to responses, a two component version tag would be necessary.~~ I did not think this 100% through and have to correct myself: Just the major version in the route is sufficient. The client should of course not be so strict to deny additional fields (because these may occur with semantic versioning for minor bumps), and for determining the minimal version supported by the server, the client can just ask the ServiceInfo.

Is this reasoning correct?

[vinjana]

The missing 1.0.1 version tag issue is clearer covered in #191. Semantic versioning is also covered in #71.

I don't see what other topics of this issue are not better covered by other issues, and propose to close this issue.

[uniqueg]

Thanks for pointing me to your comment here, @vinjana, I hadn't seen that.

As for closing this issue: I think the proposal to include frozen/tagged/released versions of the specs in separate files goes beyond what is being described in #191. Having all versions available in the same directory might be more convenient in some cases (e.g., when comparing versions) as opposed to having to check out releases individually. However, it also comes with additional complexity, on the maintenance side, but potentially also on the user/implementer side (we probably wouldn't want new implementers to think much about what version to use, but instead rather pick the latest one).

Personally, I tend to favor having just one file and let the version control take care of what it is designed for. I would, however, like if we included pushing releases to a service like Zenodo (https://zenodo.org/), so that the specs become citable (DOI). So that may potentially be a compromise here?