Versioning, releases and branches - adewg/ICAR GitHub Wiki

In the ICAR ADE standard we use semantic versioning 2.0.0 (https://semver.org/). This means that we increase our version number using the following rules:

  • change to major version indicates a breaking change
  • change to minor version indicates a planned functional release (e.g. new message)
  • change to patch version indicates a fix to the specification

Our default branch always points to the latest major version, currently ADE-1. This default branch is similar to "master" branches in other git branching strategies and contains the latest stable version. All previous minor or patch version are tagged whenever they are released so they can always be retrieved. Note that minor and patch versions must be backwards compatible; as such you should be able to simply track the ADE-1 branch and keep it up to date.

New work, as proposed via the issue tracker will be added via pull requests to the Develop branch. When the work is deemed sufficiently stable and significant enough in scope, a new release is proposed in the workgroup. If it is decided to create a new release, the Develop branch is merged back into the current major version branch (ADE-1) and the version is tagged.

How to do a release

Testing for a release

This is work in progress, just some raw notes

To test for the Java client generation, I use the following command lines to see if it compiles:

  • java -jar ~/local/openapi-generator-cli-4.3.1.jar generate -g java --library native -i https://raw.githubusercontent.com/adewg/ICAR/Develop/url-schemes/exampleUrlScheme.json && mvn package
  • java -jar ~/local/openapi-generator-cli-5.2.0.jar generate -g java --library native -i https://raw.githubusercontent.com/adewg/ICAR/Develop/url-schemes/exampleUrlScheme.json && mvn package

To test for the Java server, I use the following:

  • java -jar ~/local/openapi-generator-cli-4.3.1.jar generate -g jaxrs-resteasy -i https://raw.githubusercontent.com/adewg/ICAR/Develop/url-schemes/exampleUrlScheme.json && mvn package
  • java -jar ~/local/openapi-generator-cli-5.2.0.jar generate -g jaxrs-resteasy -i https://raw.githubusercontent.com/adewg/ICAR/Develop/url-schemes/exampleUrlScheme.json && mvn package

Generating release notes

These notes are derived from issue #99

We can use a Release Note generation tool (for example github-changelog-generator). It is important to have all changes and related issues been marked into PR/commits (refer to guide).

Steps

  • gem install github_changelog_generator

  • create a github token (github generator token) -- you only need "repo" scope for private repositories

  • merge the pull requests that need to go into the release

  • go to https://github.com/adewg/ICAR/releases

  • create a 'release' and name it according to the semantic versioning scheme: e.g. v1.0.1

  • Add a simple description, since the details will be in the changelog

  • run github_changelog_generator -u adewg -p ICAR --token <token>

  • copy the generated CHANGELOG.md to your repo and push it to Develop

  • create a pull request for ADE-1

⚠️ **GitHub.com Fallback** ⚠️