Skip to content

Latest commit

 

History

History
283 lines (210 loc) · 9.18 KB

RELEASING.adoc

File metadata and controls

283 lines (210 loc) · 9.18 KB

Releasing Kiali

This document covers the specifics of releasing Kiali, and is meant as a guide for Kiali release managers.

The summary of the process as follows:

  • Create a new JIRA issue for the release

  • Make sure Getting Started docs are complete

  • Update Kiali UI version

  • Publish the API Docs

  • Update Makefile

  • Create the Release PR

  • Tag Git Repo

  • Update JIRA issues included with the release

  • Notify Istio and Openshift Istio Teams for changes:

    • Istio Helm Charts

    • Istio Ansible Installer

    • Openshift Istio Ansible Installer (istiooc)

  • Send out notifications (twitter, mailing lists, IRC)

Creating a new JIRA issue

Create a new issue on JIRA detailing the release, and add sub-tasks if necessary.

Updating Docs

Then, next step is to make sure the "Getting Started" document for the website is up to date and works with the new version.

The docs can be found here. Update the document, and create a PR.

Updating Kiali UI

The specifics of releasing Kiali UI can be found here.

You should release Kiali UI before releasing Kiali core, as Travis will create the new image as soon as the tag for core is pushed to master.

Publish API docs

API docs are generated by Swagger, and the following command will both install Swagger on your machine and generate the updated documentation.

$ make swagger-install swagger-gen

Update Makefile

Change the VERSION variable in the Makefile to the new version. This version will be displayed in the UI, and is also what Travis will use to trigger the release process.

diff --git a/Makefile b/Makefile
index c1f7f80..aa0c54a 100644
--- a/Makefile
+++ b/Makefile
@@ -3,7 +3,7 @@ SHELL=/bin/bash

 # Identifies the current build.
 # These will be embedded in the app and displayed when it starts.
-VERSION ?= v0.9.0-SNAPSHOT
+VERSION ?= v1.0.0
 COMMIT_HASH ?= $(shell git rev-parse HEAD)

 # Indicates which version of the UI console is to be embedded

By default, the Makefile gets the latest version of the UI, so we’ll also change the console version on the Makefile:

One thing to keep in mind is that CONSOLE_VERSION comes from the npm repository, and may not be the same as VERSION (though currently the Kiali team is keeping them the same). You can get the console version here.

diff --git a/Makefile b/Makefile
index c1f7f80..1d05ff3 100644
--- a/Makefile
+++ b/Makefile
@@ -13,7 +13,7 @@ COMMIT_HASH ?= $(shell git rev-parse HEAD)
 # WARNING: If you have previously run the 'docker' target but
 # later want to change the CONSOLE_VERSION then you must run
 # the 'clean' target first before re-running the 'docker' target.
-CONSOLE_VERSION ?= latest
+CONSOLE_VERSION ?= 1.0.0
 CONSOLE_LOCAL_DIR ?= ../../../../../kiali-ui

 # Version label is used in the OpenShift/K8S resources to identify

Creating the release PR

$ git add Makefile swagger.json
$ git commit -m "v1.0.0 Release"
$ git push <your remote> master

Create a GitHub PR, have someone review it, and then merge it.

After the merge, Travis will run the test suite, build the binary, and push the "latest" docker image to DockerHub.

Tag Git Repo

Now you need to pull the latest master with the merged commit, and create the tag for it.

$ git pull
$ git tag v1.0.0 <merge commit id hash>
$ git push origin v1.0.0

Once the tag has been pushed, Travis will immediately run another build, but this time will tag the Docker image with the same version string as the Git tag name. In the example above, the Docker image pushed to DockerHub will not be tagged with "latest" but will instead be tagged with "v1.0.0".

You can let the committers know that the release has been completed and PRs can begin to be merged again. Though, it would be best to wait for this notification to go out until after you bump up the version string to the next snapshot version (see "Prepare For The Next Release" below).

Note that, in the example above, the docker image pushed to DockerHub will not be tagged with "latest" but will instead be tagged with "1.0.0.Final."

Updating JIRA issues

Edit all issues in Ready to Release state with Fix-Version:

  • Use this query https://issues.jboss.org/issues/?filter=12336798

  • Use Tools>Bulk Change>All XX issue(s)

  • Select all issues and press Next

  • Edit issues

  • Change Fix Version/s>`Add to existing`>Pick the version to release>Unselect Send mail for this update>Next>Confirm

Transition all issues to Released: * Use this query https://issues.jboss.org/issues/?filter=12337486 * Use Tools>Bulk Change>All XX issue(s) * Select all issues and press Next * Transition issues * Released>Next * Unselect Send mail for this update>Next>Confirm

After that, close the release issues, and then, create a new Release in JIRA for the next release.

Mark the current version as released, and create a new minor version: https://issues.jboss.org/projects/KIALI?selectedItem=com.atlassian.jira.jira-projects-plugin:release-page

Notify Istio and Openshift Istio Teams for changes

There are no fixed steps for releasing a new version on the Istio installer, each release is kind of different.

This has been done a few times before, so they can be used as references:

Those PRs cover both the ansible-installer and the helm installer updates.

Send out notifications

Finally, we just need to send the nofications to create awareness of the new release.

Post an email about the release on our Mailing List.

Send a message on our channel at Freenode, #kiali.

Post a message on our twitter, @KialiProject. If you don’t know who’s responsible for the account, ask on IRC.

Preparing for the Next Release

After the release happens, you’ll need to prepare Kiali for the next one. This means changing the Makefile to the defaults:

diff --git a/Makefile b/Makefile
index c1f7f80..4a8af40 100644
--- a/Makefile
+++ b/Makefile
@@ -3,7 +3,7 @@ SHELL=/bin/bash

 # Identifies the current build.
 # These will be embedded in the app and displayed when it starts.
-VERSION ?= v1.0.0
+VERSION ?= v1.1.0-SNAPSHOT
 COMMIT_HASH ?= $(shell git rev-parse HEAD)

 # Indicates which version of the UI console is to be embedded
@@ -13,7 +13,7 @@ COMMIT_HASH ?= $(shell git rev-parse HEAD)
 # WARNING: If you have previously run the 'docker' target but
 # later want to change the CONSOLE_VERSION then you must run
 # the 'clean' target first before re-running the 'docker' target.
-CONSOLE_VERSION ?= 1.0.0
+CONSOLE_VERSION ?= latest
 CONSOLE_LOCAL_DIR ?= ../../../../../kiali-ui

 # Version label is used in the OpenShift/K8S resources to identify

Finished Product

Once the above steps have been performed, the release is complete. There is now a DockerHub image for that release in the Kiali Docker Hub repo.

How It Works

Most of the magic is set up in the .travis.yml file.

If the Travis build is a tag build, then the tag name is passed to all Makefiles as the value of the DOCKER_VERSION environment variable. The Makefiles use that to tag the docker images when building and pushing the images to DockerHub.

If the Travis build is a branch build (that is, not triggered by a tag), the name of the branch is set to the DOCKER_VERSION variable with the exception of the master branch. If the branch name is master, the DOCKER_VERSION is set to "latest". Again, the value of the DOCKER_VERSION variable is then used by the Makefile to tag the docker images.

Note that only tags or branches in the format v#.#.#[.Label] will trigger release tag/branch builds.

Creating a Hotfix

Sometimes there’s the need of adding a hotfix to an already released version. That’s what the patch number on the version is.

The first step is to create a new patch branch for the major/minor version if it does not yet exist. Create the patch branch based on the release tag:

$ git checkout -b v1.0 v1.0.0
$ git push origin v1.0

Then we cherry-pick the commits that we need, or create PRs targeting this branch. Note that commits pushed to this branch might need to be mirrored on master, else those commits will be lost.

Don’t forget to change the Makefile to bump up the VERSION and CONSOLE_VERSION. So in our example, you would commit a change to the version such that it is "1.0.1".

After the fixes have been committed/merged to the new patch branch, create a new patch-version tag:

$ git tag v1.0.1 <hash-of-last-commit-to-v1.0-patch-branch>
$ git push origin v1.0.1

Now make sure the Docker Hub tag v1.0 points to the new v1.0.1 image.

And that’s it.