No tag/release for version 1.0.1

[uniqueg]

The reference documentation linked to in this repository's README.md is for version 1.0.1 of the specification. However, there is no corresponding release and/or tag for version 1.0.1 (latest tag and release are for v1.0.0).

Moreover, I seem to be unable to find the commit from which the specification linked to at the top of the reference documentation is derived. While the version string in the specification itself seems to have been bumped in this commit, the (state of the) specification in that commit does not seem to match the specification linked to in the reference documentation.

As it is of critical importance that implementers choose a definite version of a specification to develop against, it would be great to:

• Identify what exactly v1.0.1 constitutes
• Tag the corresponding commit
• Create an associated release
• Ensure that the version of the specification linked to in the reference documentation matches the one in that release

Compare also #192 and #193

[vinjana]

In this comment I refer to the versioning scheme. I just want to mention it here because, I think, if we want semantic versioning (SemVer2) then the version that is now published in the reference documentation as 1.0.1 should actually be 1.1.0 (at least), because it adds fields to the ServiceInfo, and API additions qualify for minor bumps according to SemVer2. I think it would be fine to tag this version both 1.0.1 and 1.1.0 and document this in the changelogs. Just an idea.

[uniqueg]

Thanks @vinjana. Agree on SemVer, and I think that was the original intention. Given that there is not a tag/release yet for v1.0.1, I think it's indeed an opportunity to change the version to v1.1.0 and then create the release.

I also agree with you on the more general points on having a clear governance regarding the creation of releases (ideally across -at least- the GA4GH Cloud WS APIs).

[vinjana]

Duplicate of #157 .

[uniqueg]

Oops, sorry. But guess it's time to track down the relevant 1.0.1 commit then :)

[vinjana]

What about keeping 1.0.1 anyway, but marking it as deprecated. It is possible to put two tags on a commit, e.g. 1.0.1 and 1.1.0. This would also express that these versions are actually the same. Probably some sites use the 1.0.1 tag (e.g. Sapporo, which even has a copy of the spec in the repository -- at least of the version they considered 1.0.1).

[uniqueg]

Hmm, I don't quite understand how tagging the v1.1.0 commit with v1.0.1 and then deprecating v1.0.1 would help anyone. They were certainly not meant to be identical, and it may further confuse people.

I personally would prefer that someone actually makes a judgement call on what v1.0.1 was (e.g., the commit that actually bumped the version in the specs would be a reasonable candidate if we have no further documentation; or use the commit that Sapporo is using) and then run with that. As long as the reference docs only point to the last release, with the v1.1.0 release they don't even have to be updated to match v1.0.1. So it'd just be a matter of checking out the commit, tagging it, pushing and creating a release.

[vsmalladi]

@uniqueg I think that the commit for v1.0.1 from the main branch.

Do we have a release for v1.1.0? If not I think we can release 1.0.1 with a tag on the main/master branch.

[uniqueg]

Great find, @vsmalladi, thanks a lot. I don't think there's a release for either 1.0.1 or 1.1.0: https://github.com/ga4gh/workflow-execution-service-schemas/releases. So yes, tagging the commit you identified with 1.0.1, pushing and creating a release would be great. And then the same with 1.1.0 as well, because there also is neither a tag nor a release at the moment. And while at it, perhaps the release name for 0.3.0 could also be changed for consistency.

Ideally we would of course automate this flow, e.g., whenever another branch is rebased onto the main branch, a tag should be added and a release created. A changelog could be autogenerated from the commit titles, especially when Conventional Commits are used: https://www.conventionalcommits.org/en/v1.0.0/

Similarly, we could automate pushing updates to the documentation with each release, ideally in a way that keeps older documentation versions accessible.

And then we could also think about pushing releases to Zenodo or Medline or whatever (there was a discussion on that on the Slack board) so that the versioned releases are archived and assigned DOIs. Being able to cite a general and or specific version of WES would be great.

Of course, that flow could be reused for all (Cloud) API specs.

Might be a good topic for a hackathon.

Anyway, to close this issue, I'd just be happy with at least a tag on the commit you identified.

[vsmalladi]

@uniqueg Great. I can't add any new tags or releases on master branch. So that might be up to you or @wleepang or @patmagee

[uniqueg]

I probably don't have more permissions than you have, so yeah, I guess this goes to @wleepang and/or @patmagee 🙏🏻

[wleepang]

Are we sure it's not this commit that needs to be tagged? This is where I see 1.0.1 appear in the spec.

[uniqueg]

Could be, I don't know. I guess at this point it's just important to tag any one commit we can agree on :)

[vsmalladi]

@wleepang i do think that the intention was for this commit to be the1.0.1 release, however there seems to be a merge after that fixes service info so that it validates. So my opnion is the commit that does the fix and passes test should be the version we tag.

[uniqueg]

Given that we have some leeway in deciding what's v1.0.1 after more than two years of people not freaking out, I think @vsmalladi's reasoning makes perfect sense to me. It also has the additional advantage of being on the tip of master for more than two years, and thus there's a reasonable chance that some people may have developed against it.

So +1 for commit 13f5682 from my side

[wleepang]

I've tagged commit 13f5682 as 1.0.1 and pushed the tag. This commit is on master, but most of our recent updates have been to develop, so the two branches have diverged a bit.

In particular, the tagged commit in master is not in develop. I've also submitted PR #200 to address this.

[vsmalladi]

@wleepang can we close this issue now?

[uniqueg]

Actually, I have just realized that the v1.0.1 tag points to a commit on branch develop.

I think it is better/safer to have release tags only pointing to commits on the main (here: master) branch instead, with the head commit on that branch always being the commit that is tagged for the most recent release. I would then also suggest to make the main branch (we might actually rename it to main in case anyone is bothered by master) the default branch so that potential implementers will always be pointed to the commit representing the latest version if they stumble on the repository.

This is described in #193 in some more detail, but I would just like to point out again that this is important, because I have just realized that the commit tagged for the v0.3.0 release is not associated with any known branch on this repo (visit https://github.com/ga4gh/workflow-execution-service-schemas/releases/tag/0.3.0 and click on the link pointing to the associated 50987ae commit, then have a look at the yellow banner at the top), which is surely not great. Similarly, the develop branch may sometimes be unstable, for example if it needs rebasing against master/main after merging in the commits for a new release, e.g., from develop or a dedicated release branch.

In summary, personally I would prefer to merge develop into master/main first such that the head commit points to the commit we chose to represent v1.0.1, then retag 1.0.1 for that commit on the master/main branch and recreate the release. Then we need to make sure that develop and the master/main branch share the same history (merge back or rebase if it is not) and then we should be good. So basically, let's first address #193 before we properly address this issue.

[vsmalladi]

I agree tag to 'main/master' is the best way to do this.

@uniqueg I beleive that v1.0.1 commit is the head of master/main now.

[uniqueg]

Oh, yes, you are right. Given that it's the same commit, I'm wondering why it shows up as being part of a specific branch at all:

Got to this screen after following the commit that is associated with the tag.

Maybe this is because develop is the default branch?

[uniqueg]

Anyway, it seems that my concern is not relevant here. The only thing left to do, from my perspective, is to change the default branch, but that's #193. So I guess from my side the issue can be closed.

[wleepang]

What I attempted to do was tag 1.0.1 on master and then PR master into develop. As far as I can tell from the commit/branch network this happened.

[patmagee]

@uniqueg this seems like it is done, can I close this?

[uniqueg]

I have confirmed the first three points just now. If you can verify that the reference documentation points to the 1.0.1 release, then I think this is done indeed.

[vsmalladi]

@uniqueg can we confirm we can close this?