Default branch & release model

[uniqueg]

Before the WES API was officially adopted by the GA4GH, it was voted that the develop branch should be the default branch for WES (and other Cloud APIs) for reasons of convenience at a time when no definite release was yet available and development was still very dynamic.

At this point though, I think it is important to emphasize to visitors that the API is officially adopted and reasonably stable. Changing the default branch to master (perhaps better rename to main) might help reflect the maturity of the standard.

Following the Git Flow branching model, I would also propose that the master/main branch is the one against which tags (and releases) are defined, and that its head is always the commit that is associated with the latest release. This will increase the chances that (new) implementers will use the same version of the specification (compare #191).

The following model for new releases is implied:

• Cherry-pick the desired commits for a particular release into a release branch
• Merge release branch into default (master/main) branch
• Create release; should include the following (not necesarrily in that order):
  • Tag merge commit (or last commit for linear commit history)
  • Create changelog (autobuild or manually)
  • Build docs (autobuild or manually)

[vinjana]

and that its head is always the commit that is associated with the latest release

Not sure whether this particular sentence/proposal is a good idea. I guess we currently have a development branch, because there are so many changes that are not yet release-ready. The proposal suggests to either merge them directly into main/master -- automatically bumping the version because of the statement above, because a release needs a version number -- or keeping them on feature branches until a release is planned.

I have used two modifications of the scheme in my projects:

• Only consider tagged commits as releases and allow tags only on the main/master branch. It is fine to e.g. discriminate between release-tags, that follow some pattern (e.g. \d+\.\d+\.\d+) and other tags, and only consider release-tags as releases. Release-tags could be automatically be build to be deployed into the documentation.
• Instead of having a long-running but unspecific development branch, have release branches. For every PR feature it is then decided, into which release-branch it goes. Having just a single release branch will and should be the standard, but I can imagine that as e.g. SemVer2 is done strictly, then the need may arise to postpone breaking changes to later releases. The main branch may then only get the merge commits when merging the release-branches (if you want).

I think both approaches have their advantages. Probably the second is more flexible.

Overall, I think a defined release strategy plus accompanied process for planning releases would be nice and appropriate for a standard. That could be as simple as having such a branch model (which-ever) and deciding on release contents and maybe dates in some meeting or even discussion here on Github. Releases could also be planned better, if there was a project board in Github, in which all issues are sorted (backlog, in progress, done), maybe with a top-sorted backlog. Actually, I think that such a planning is very transparent to the users of the standard, which will further trust and maybe participation.

[uniqueg]

@vinjana - The Git Flow model was chosen as the branching model for the Cloud WS APIs years ago, but this may have been forgotten. That model includes release branches, which I was also proposing to make use of:

Cherry-pick the desired commits for a particular release into a release branch

Perhaps I was not very clear, but my intention was to suggest following Git Flow. In that branching model, only hot fixes are merged directly into the default branch (master/main). Indeed those would require a version bump - as they should! But probably/hopefully that is anyway not too relevant for us.

Here's a cartoon outlining that model:

Basically, it's similar to your second suggestion with the difference that a a long-lasting development branch is still retained, in order to always have a single branch to create feature branches off and allow contributions to build upon one another, between releases. This makes it easier on contributors, who wouldn't necessarily need to know about SemVer and the full implications of their PRs when picking a release branch (patch, minor or major) to create their feature branches off (and to file their PRs against). On the other hand, it may be harder on maintainers, who may need to disentangle commits to the development branch from one another when preparing release branches, say, patch from minor/major changes when preparing a patch release, or merged patch/minor changes from major changes when preparing minor releases.

Anyway, I fully agree with you that probably the specifics of the branching model are less important than choosing one and running with it. A regular release schedule (e.g., patch versions every 3-6 months, minor versions annually, major versions every 2 years) may also help, because occasionally have the urge to suggest breaking changes, but then I don't because I just don't see how they would ever get merged (and by the time a major change may be merged, the PR will very likely be hopelessly outdated).

[vsmalladi]

I agree i think a more regular release schedule will help this.

Can this be brought up in the next Cloud WS meeting?

[uniqueg]

+1 on bringing this up and maybe making an automated release flow a priority, possibly for a hackathon?

Would also like to note that this would be ideally a cross-WS effort, as such a flow would probably be useful for all (Open)API specs.