Streamlined API release policies

[uniqueg]

The problem

API product managers currently each design their own process (possibly with guidance from the corresponding) for releasing updates. This involves a number of decisions to be made and artifacts to be generated and may therefore slow down the release process and lead to inconsistencies between standards or even mistakes.

It would be great to define guidelines/policies for releases and reusable artifacts to streamline the process of GA4GH API products.

The solution

Guidelines could be drafted that cover, for example:

• How and where API specifications should be published (e.g., GitHub, Crossref)
• If/how commits should be tagged
• What Git branching model to adopt (e.g., Git Flow, GitHub Flow, GitLab Flow) and how to apply it in preperation of future releases, considering that there may be multiple options (next release could be patch, minor or major); this should ideally not just reference the branching model, but concrete info, e.g., keep main (for releases only, head commit always points to latest release), develop (working branch to create feature branches off), release branches for next patch, minor, major release
• How SemVer applies to API changes; again, guidelines for the most common scenarios should be concretized
• What merge strategy to adopt / linear vs. non-linear history and how the merge strategy impacts the release process
• What other GitHub options to set
• How to maintain, update and publish (continuous) documentation, where to publish them and if and how to keep versioned documentation
• How specs, code and data should be licensed
• How to write and keep release notes and changelogs
• How the process can be automated as much as possible (e.g., whole release process is triggered automatically if commit message includes specific regex)

Reusable artifacts could include:

• A checklist for creating a new release
• GitHub repository template with boilerplate following the guidelines above
• GitHub Actions workflows or specific Actions for releases, docs, OpenAPI linting/validation etc.
• Templates for releases notes/changelogs, GitHub issue, PRs
• Boilerplate parts for the documentation (links to GA4GH, Code of Conduct, contributing guidelines etc.)

Additional context

A lot of these guidelines are already in place, implicit or explicit, across the various API products. Similarly, a number of the artifacts may already exist and may already be reusable.

Therefore, a survey of the different available guidelines, solutions and artifacts would be useful to further inform the requirements and the work necessary to provide the support as outlined here.

Of course, guidelines and corresponding artifacts could themselves be versioned and iteratively improved/amended.