Skip to content

Releases

Jump to bottom
David Majda edited this page Jan 25, 2016 · 9 revisions

This document describes how we do Juttle releases and serves as a guide for everyone participating on them.

Goals

Our main goal is for everyone to have a smooth experience when installing, updating, and using Juttle (both as a user and as a developer). We want to deliver new features quickly and at the same time allow for a stable environment that can be depended upon. While technically, Juttle-related projects are split into multiple repositories and npm packages, we want to enable users to experience Juttle as a whole, without the need to deal with the low-level structure.

Release Scheme

The goals stated above led us to a scheme where we release new versions of all main Juttle components together every 2 weeks. This provides regularity and fast feature delivery while maintaining cross-component coherence. For most users, the most important component released is Outrigger, which is in fact the final result of each release. See below for the full list of Juttle components that are part of regular releases.

Occasionally, we may also release bug fix releases (which deliver bug fixes only) and out-of-order releases (which also deliver features). These releases will typically encompass only some components. In further text we assume a regular release.

Release Workflow

We do the releases in staged, distributed, and coordinated fashion. This means:

  • Components are released according to their dependencies. First, new version of juttle is released. Then each component depending on it is updated to work with the new version and a new version of it is released. This continues until the whole dependency chain is traversed and finally new version of outrigger is released.

  • Components are released by their owners. Each component has an owner who is responsible for releasing new versions of the component. This is usually the person who does the most development and has the most knowledge about the component. Each component also has one or more covers, who can cover for the owner when he/she is unavailable. Both owners and covers have necessary permissions to do the release.

  • The state of the release is tracked. At each point it is clear which components are released, which are being worked on, and which are waiting for their dependencies. This is accomplished by using a tracking issue.

The release starts on Wednesday CET with the release of a new version of juttle. On Wednesday PST the owners of other components take over and start adapting and releasing new versions of their components, updating the tracking issue as they go. Finally, new version of outrigger is released and the issue is closed. The goal is to get into this state by Friday PST.

List of Components

Here is a list of components that are part of the release with their owners and covers, ordered roughly by their dependencies:

Component Owner Covers
juttle @dmajda @demmer
juttle-elastic-adapter @davidvgalbraith @demmer
juttle-gmail-adapter @mstemm @demmer
juttle-graphite-adapter @rlgomes @demmer
juttle-influx-adapter @bkutil @demmer
juttle-mysql-adapter @VladVega @demmer
juttle-opentsdb-adapter @VladVega @demmer
juttle-postgres-adapter @VladVega @demmer
juttle-sql-adapter-common @VladVega @demmer
juttle-sqlite-adapter @VladVega @demmer
juttle-twitter-adapter @demmer ?
juttle-viz @go-oleg @demmer
juttle-client-library @go-oleg @demmer
outrigger @mstemm @demmer

Releasing a Component

Major or Minor Version

When releasing new major or minor version of a Juttle component (e.g. 0.5.0) as part of a regular release, use the following steps:

  1. Make sure you are ready to release code-wise. In particular, go through open PRs and make sure all that are needed for the release get merged. Also make sure the tests are green both locally and in Travis CI.

  2. Make sure new versions of all changed dependencies have been released. You can determine this by looking at the tracking issue.

  3. Create a branch for changes related to the release and switch to it.

  4. Edit package.json to update versions of all changed dependencies and commit that change. Note that in some cases we use >= instead of ^ to specify a dependency version so no update may actually be necessary. In any case, make sure you have updated versions installed locally using npm update before proceeding further.

  5. Update the code to adapt to breaking changes in updated dependencies. This mainly involves walking through dependencies’ changelogs, running tests locally, and exercising things manually as appropriate. Commit any changes in separate commits, each dealing with specific adaptation.

  6. Write a changelog entry for the new release. It should contain all changes done since the last release which can affect the user in any way. It doesn’t need to mention internal changes, fixes such as typos, etc. In general, after reading the entry the user should have a good idea what changed since the last version and what he/she will need to adapt after the upgrade. Put the changelog modification into a separate commit.

It may happen at this point that you’ll find there are no changes since the last release and that the component works just fine with new versions of its dependencies. In that case, skip releasing the new version and go to the last step.

  1. Get the changes in. Create a PR from your branch, get a review the usual way, and merge it.

  2. Release new version. To do that, use cut-release. It will update package.json, create a tag, push the changes to GitHub and publish a npm package. Use semantic versioning rules to decide what version number the new version should have.

  3. Add the release to GitHub. Go to the Releases tab and add your new release, copying the changelog entry as its description.

  4. Mark the component as released. Check the checkbox in the tracking issue, add the version number of the last release there (so others don’t have to look it up), announce the release as appropriate, and ping owners of any depending components.

Patch Version

When releasing new patch version of a Juttle component (e.g. 0.5.1), use the following steps:

  1. Create a branch for patch releases and switch to it. For example, when releasing version 0.5.1, create a 0.5.x branch based off the v0.5.0 tag.

    Skip creating the branch if the released version is not the first patch version based on given major or minor version and the branch already exists (e.g. when you are releasing version 0.5.2 and you already created the branch when releasing 0.5.1).

    You can also skip creating the branch and release directly from master if there are no changes in the code since the last release except the fixes you want to publish now.

  2. Make sure the fixes you want to publish are in. Typically, this means creating a PR against your branch with the fixes and appropriate changelog entries, getting a review the usual way, and merging it. Make sure the tests are green both locally and in Travis CI with the fixes in.

  3. Release new version. To do that, use cut-release. It will update package.json, create a tag, push the changes to GitHub and publish a npm package. Use semantic versioning rules to decide what version number the new version should have.

  4. Add the release to GitHub. Go to the Releases tab and add your new release, copying the changelog entry as its description.

  5. Merge the patch releases branch back into master. This will ensure convergence of the code, changelog entries, etc.

  6. Announce the release as appropriate. Ping owners of any depending components if the release is done mainly to unblock them.

Clone this wiki locally