Healthcare Data Exchange Release

[balteravishay]

Today, Healthcare Data Exchange project is not following a versioned release with a unique version identifier for each release intended to be used by users. The intent is to add a Semantic Version (SemVer) and leverage the GitHub release functionality to version Healthcare Data Exchange. For simplicity, at first step, the release mechanism should be manually triggered.

[frtibble]

Hi @johncollinson2001, @balteravishay, including an initial proposal on this here - comments, questions welcome:

Using GitHub Release to manage project versioning

Context

Versioning allows users and developers to track changes between deployments, either by comparing code differences between versions or by referring to a changelog.

It also signals to users the nature of the changes, such as breaking changes, new functionality, or bug fixes, through the use of semantic versioning.

GitHub Releases is a built-in feature of GitHub repositories which allows you to package a version of your software. This is done using Git tags which marks a specific point in the repo history.

Decision drivers

• Minimal process (it should be straightforward to publish a release)
• Small time overhead (steps should be automated where possible)
• Low maintenance solution

Proposal

• Use semantic versioning: Semantic versioning helps describe the nature of changes using major, minor and patch version increases.

  Example: a repo with version 1.0.0 has a major version 1, minor version of 0, and patch version of 0. When breaking changes are made, the major version should increase, e.g. to 2.0.0. When new features are added which are backwards compatible, this should increase the minor version, e.g. 1.1.0. If bug fixes are made, this should increase the patch version, e.g. 1.0.1.

• Require PR title to use semantic versioning: One advantage of semantic versioning is that by adhering to the specification, the version number of a release can be automatically calculated. This means someone does not need to manually review which PRs have been merged and tag the release themselves.

  Example: If a PR is merged to main which has the title fix: uses correct formatting of organisation address, then an automated workflow will be able to detect from the fix keyword that there is a patch version increase required due to the bug fix.

• Use a GitHub Action to publish releases: An Action can be added which can be triggered by a successful CI build when a change is merged to main. In this way, only changes which have passed necessary checks can be part of a release. This GitHub Action would then run, review the commit history, and if there are changes which would cause a release, this would be automatically created.
• Manual releases: If required, it would also be possible to create a release manually, or delete a release. This can be done via the UI.

Tasks

• [x] Enable GitHub Releases on the repository - already enabled
• [ ] Add a Pull Request template to repo, this will include guidance on what info/checks a dev should complete before creating a PR
• [ ] Add a GitHub Action which checks that PR titles adhere to the correct format, info would be included in the PR template with guidance on how to name a PR, i.e. which prefix to use (e.g. fix, feat, build, etc)
• [ ] Add a GitHub Action which creates releases when a successful CI build completes after a merge to main
• [ ] Add Release Guidance docs which explain semantic versioning, PR title naming, automated releases via GitHub Action, manual releases, security/permissions of release action

Other links

• See this repository for an example of what PRs would look like with a PR title checker and a requirement for a semantic version prefix
• See releases in that same repository for an example of the github-actions bot publishing a release (note that, the release notes are automatically generated from the PR titles).

[balteravishay]

This looks great, thanks for taking the time to propose this @frtibble! I support this standard, easy to maintain solution. @johncollinson2001 , wdyt?

[johncollinson2001]

Hi @frtibble @balteravishay

Thanks for putting this together, it looks great! I have a few questions...

• Can you confirm... will the github action calculate version number, add the tag to the repo, as well as create the release? Is there much custom scripting required for this? I can see in the link above it uses https://github.com/codfish/semantic-release-action, would we probably use the same?

• You mention the PR titles are used to by the action to figure out if it's a path/minor/major, is there any more info on this? E.g. how it's configured (e.g. fix -> patch, feat -> minor, what decides major vs minor?)

• Manual release - this is completed by manually running the GH action?

Thanks!

[frtibble]

Hi @johncollinson2001!

• For the release, yes the github action calculates the version, adds the tag, and creates the release. It would use the action https://github.com/codfish/semantic-release-action, which doesn't require anything custom, however does have different configuration options that we could tweak.
• On determining the version number, yes, so in https://semver.org/ the spec says that a patch is required for a bug fix, minor version increase is for any backwards compatible changes, and major for any breaking changes. There are different conventions which implement this spec, and the one I'd suggest we use is https://www.conventionalcommits.org/en/v1.0.0/#specification, which e.g. says:

  1. Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.
  2. The type feat MUST be used when a commit adds a new feature to your application or library.
  3. The type fix MUST be used when a commit represents a bug fix for your application.

We can specify which convention we're using in the github action (which is one of the configuration options it supports, we can also customer the release notes as well for example).

• For manual releases, this isn't done using the github action, it involves these steps: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release. There is an option built-in to generate the release notes, the main thing that is required when doing a manual release is the person creating it will need to determine what the version number for the tag would be.