Kabanero Release Best Practices

Projects that are included in Kabanero should attempt to adhere as close as possible to the following release practices.

Once the following practices are read and understood, you should create a wiki page in your GitHub repository entitled "Release Process", based off of the Kabanero Release Process Template.

Kabanero Iterations

Kabanero is developed in 2 week iterations, as shown in the Kabanero Iteration Schedule.

Kabanero Foundation will cut a formal release every 4 weeks, at the end of even-numbered iterations, and this will be considered a "Kabanero Release".

It is recommended that Kabanero feeder projects cut releases every 4 weeks, but at the end of the odd-numbered iterations, to allow an additional iteration for Kabanero Foundation to update to new releases of dependencies.

Creating a Release

A "release" in GitHub is created by choosing a version number (see below) and pushing a tag to your repository with that version number. Once the tag has been pushed, you can use the GitHub UI to browse the tag and click "Edit release" to provide more details about it (for example, the location of a container image associated with the release on DockerHub).

Release Versioning

Release versions should adhere to semantic versioning (https://semver.org/) and are generally of the form [MAJOR].[MINOR].[PATCH][-OPTIONAL]. For Kabanero feeder projects, it is recommended to do the following:

• Do not prefix the release version with the letter "v".

• Use major version "0" to start with and do not increment the major version without consulting the release architect.

• Start with minor version "1" and increment it for each release, e.g. 0.1.0 then 0.2.0 then 0.3.0, etc...

• Use patch version "0" when creating a regularly scheduled release. At some point, it may be necessary to patch a scheduled release with bug fixes. When that happens, we can create a branch based on the release we are patching, patch that branch, and then create an unscheduled release from that branch that increments the patch version.

• For a regularly schedule release, create a "release candidate" first, using the optional suffix "-rc.1", e.g. 0.2.0-rc.1.

• Each Kabanero feeder project needs to define validation criteria that must pass in order for a release candidate to become a formal release.

  • Validation critera should be determined separately for each team, consulting with the release architect as necessary.
  • Validation of a release candidate should NOT require a new release of any other project except for the one being validated. For example, validation of a new release of the Kabanero Operator should NOT require a new release of Kabanero Foundation.
  • Validation should consist of Functional Acceptance Tests, not System Test.
    • System Test comes into play for Kabanero Foundation only, not for individual projects.
  • Ideally, release candidate validation should be done by an automated set of Functional Acceptance Tests launched from the build. This is not realistic at first, so it is understood that initial release candidate validation will be done manually. This validation criteria should be documented in the project's RELEASE.md (see below for a template).

• If a release candidate fails validation, additional fixes should be merged and a new unscheduled release should be created that increments the release candidate version, e.g. 0.2.0-rc.2, 0.2.0-rc.3, etc...

• When a release candidate passes validation, a new tag should be pushed that removes the release candidate qualifier, e.g. if 0.2.0-rc.3 passes validation, a 0.2.0 tag should be pushed at the same commit.

• Unscheduled pre-releases can be created at any time. They should use the major, minor, and patch versions of the next scheduled release, but with an "-alpha" qualifier that contains an incrementing alpha version. For example, if the next scheduled release is 0.3.0 and this is the first unscheduled release you are creating prior to 0.3.0, you would name it 0.3.0-alpha.1 (followed by 0.3.0-alpha.2 for the next one, etc...).

Building a Release

For projects that don't have a build associated with them (e.g. "docs"), the above process is all you need. Most projects, however, will need to run a build against a given release and update the release documentation to point to the build artifacts.

• The currently recommended way to do this is to use Travis CI/CD (https://travis-ci.org/).
• Your project must contain a ".travis.yml" file before it can be enabled for automatic Travis builds. The Travis documentation (https://docs.travis-ci.com/) contains full details, and you can also see the "kabanero-operator" repository for an example.
• When you have an appropriate ".travis.yml" file in your project, contact the release architect to enable your repository for automatic Travis builds.
• Most builds will publish a container image to DockerHub under the "kabanero" ID. The release architect will help you configure your build to set the appropriate user name, password, and image name as environment variables of the build. Again, the code in "kabanero-operator" contains an example of publishing a container image from the build.

Post-release Actions

• Your GitHub release should be updated to contain information related to the release. This could include, but is not limited to:

  • Locations of built artifacts such as container images published to DockerHub.
  • Prerequisite software versions.
  • A list of new features.

• After releasing a new version of a project, consider whether Kabanero Foundation should be updated to the new version. This may or may not be necessary depending on whether the new release contains feature code or bug fixes required by the foundation project.

  • If you are unsure, consult with the Kabanero architect to determine whether Kabanero Foundation needs to update to this release.
  • If Kabanero Foundation does need to update to this new release, open an issue in the Kabanero Foundation repository with the title "Update <organization/repo> to version ", e.g. "Update kabanero/kabanero-command-line-services to 0.2.0".
  • Add the label "dependency update" to the issue.

• Kabanero Foundation will update to new versions of dependencies in a controlled manner, allowed system test to test each update independently.