Adding an additional Release Branch

A “release branch” is a git branch on your GitHub repository from which you wish to maintain versions of your software project.

Expeditor works under the assumption that your software project is developed using the GitHub Flow. This means that the master branch is associated with the “latest” (or “currently in development”) release of your software project. However, your GitHub repository may also have other release branches, which contain long-lived branches for previous releases of your software project that are kept around for any number of reasons. For example, we maintain multiple release branches of Chef Infra Client (master and chef-14) and Chef InSpec (master and 3-stable). Expeditor handles this scenario by having these projects specify multiple release branches in their .expeditor/config.yml file.

Getting Started

The most common scenario for needing to add a new release branch bumping the major version of your software project. Your latest major version lives on master while your previous major version goes to live on a new stable branch.

Adding a new release branch requires three steps:

Merge a pull request that adds the new release branch to your configuration on the master branch. Create the new release branch off of master. Update the major version on master. Create the agent for the 1-stable release branch.

The physical release branch does not need to exist before adding it to the .expeditor/config.yml.

In our example below, we will update a project from 1.x to 2.x while maintaining a 1-stable branch.

Step One: Updating the .expeditor/config.yml on master

Expeditor uses the [github.release_branch])/docs/reference/configuration/#github-release-branch) setting to determine which branches in a GitHub repository are release branches. Being specified as a release branch in the .expeditor/config.yml file on the master branch allows that branch to have its own agent and act as an independent project.

.expeditor/config.yml
  github:
    release_branch:
      - master:
-         version_constraint: "1.*"
+         version_constraint: "2.*"
+     - 1-stable:
+         version_constraint: "1.*"
 
One of your release branches must always be master.

After you merge this pull request, Expeditor will allow an agent for the 1-stable branch to exist. The act of adding a release branch to your .expeditor/config.yml does not create the associated agent or the branch. Those will be taken care of in subsequent steps.

Step Two: Creating a stable branch in Git

After defining the release branch in your .expeditor/config.yml and merging the pull request to master, you can now create the branch in git.

git branch 1-stable
git push origin 1-stable

At this point, you have a 1-stable branch on GitHub with the same configuration as your master branch. From this point on, you’ll be able to manage the configuration for your master release branch and your 1-stable release branch independently.

Step Three: Bumping the major version on master

There are two ways to bump the major version of your project:

Merge a pull request that leverages a label specified in github.major_bump_labels Merge a pull request that updates your github.version_file accordingly.

Step Four: Creating the agent for the 1-stable release branch

There are two ways to create the agent for your new release branch:

Contact Release Engineering and have them load the new agent for you. Merge a pull request into your new release branch modifying the .expeditor/config.yml file.