Mandolin Creek System Helpers (MCSH)

Release Manager Guide

This document was written to provide a checklist for using the MCSH scripts to produce releases of packages developed using the MCSH Development Environment (IDE).

Contents

Table Of Contents
Release Policies
Release Wizard
Release Process
- Setup
  - Clone the Repository
  - Release Failures
- Manual Releases

Release Policies

This section outlines all project policies that must be followed by a MCSH Package Release Manager.

Important

Some of these policies will only begin to apply after the first major release of the package (v1.0.0).

Release Versions

The MCSH IDE reads the package configuration files to find the current package version setting. For simplity, the MCSH IDE requires that its packages use the following version format:

<major>.<minor>.<micro>

The package.i7 file must define VERSION with the current package version. Once set, the release scripts will manage changes.
The site.i7 package configuration file may define SITE_VERSION. If it is defined, its value must also follow that form.
The site.i7 file may also define SITE_BRANCH.

Release Branches

Each release offers a point of a divergence for future releases. Several kinds of branches are used track different development activity:

The master branch tracks the very newest version of the code.
A stable branch tracks improvements to a past major release.
A support branch tracks changes to a specific stable release, providing critical-but-unintrusive fixes and improvements.

Branch Policies

The following policies apply to all branches in the package repository:

A branch must diverge directly from a revision with a release tag.

Master Branch

The following policies apply to the master branch of the project repository:

The master branch must track the most current development.
The master branch must track development of:
1. the next major release, or
2. the next stable release for the most recent major release.
When forking the stable branch for the next major release, the master branch must be set to a number that the previous stable branch can never reach (e.g. the v2.0.0 development branch might use 1.61803399.0).

Stable Branches

The following policies apply to all stable branches in the project repository:

A stable branch must only contain minor and support releases.
A stable branch must only include patches for any lingering portability, stability, and performance issues.
A stable branch must be named relative to its major version. For example, the v1.0 release will be forked into a v1.x branch.
A stable branch may be created when making a major release; however, subsequent minor releases may be preferred over starting major new development.
A stable branch must diverge from the master branch before package maintainers begin work on the next major release milestone.

LTS Branches

The following policies apply to all LTS branches in the MCSH project repository:

An LTS branch must only contain support releases.
An LTS branch must be named relative to its minor version. For example, the v1.0.0 release may be forked into a v1.0.x LTS branch.

Release Types

There are three different types of pcackage releases:

A major release delivers new functionality or incompatible changes. These releases may be unstable until refined further, so they are further developed on a branch.
A minor release delivers changes on a branch of a major release that fix defects, provide minor feature enhancements, or improve the documentation. Most package releases are minor.
A support release delivers fixes to critical issues discovered in the last release. Continuous integration and test coverage should prevent the need to produce this type of release.

Major Releases

All major releases must follow these policies:

A major release must increments the <major> version by 1 and set the <minor> and <micro> versions to 0.
A major release must be repaired on its stable branch. The master branch may serve as the stable branch immediately following a release.
A major release may be supported past two future major releases For example, the v1.x branch should receive fixes past the v3.0.0 release.

Minor Releases

All minor releases must follow these policies:

A minor release must increment the <minor> version by 1 and set the <micro> version to 0.
A minor release must be made from either: - the master branch, or - a stable release branch.
A minor release should be supported past two (2) subsequent minor releases or two (2) months, which ever period is longer. For example, the v0.20.0 release, made on June 24, 2017, should be supported until either the v0.22.0 release or August 24, 2017.

Support Releases

All minor releases must follow these policies:

A support release must increment the <micro> version by 1.
A support release must be made on an LTS branch.

Bug releases must be produced:

if the last release contains a critical issue, or
when a customer with an active contract requests one.

Some customers require exceptional stability for production tools.

Most users will be happier following the series of minor release produced from one of MCSH's stable branches, as those are the primary release mechanism for delivering long-term stability and performance fixes and enhancements.

Frequency

Release early, release often: Releases should be made regularly.

Release Wizard

The MCSH Development Environment (MCSH IDE) provides tools that automate the entire release process. The following command performs everything required to produce, publish, and announce a package release:

p7 release wizard (major|minor|micro)

The Package Release Wizard reference documentation provides a description of the process. Every step of the process may be performed using other p7 commands

Release Process

Setup

The following steps must be taken prior to producing a package release.

Clone the Repository

The release process must be run in a dedicated clone of the repository dedicated to that purpose:

git clone https://github.com/mandolincreek/mcsh.git

!DANGER!

The MCSH release scripts will discard all artifacts in the working copy and make changes to local branches.

Release Failures

If something goes wrong during the release process, the entire repository may be abandoned, if and only if` the release process has not published the release tag or any deliverables.

If part of the release has been published, then:

The repository must be kept intact, and
The release process must either be:
1. completed by executing the remaining commands manually, or
2. reverted completely.

Manual Releases

The Release Wizard remains fragile, due to the number of steps involved. Consequently, a failure requires either backing out changes from the failed commit, finishing the last few steps of the process by hand, or abandoning the release repository entirely.

Note

For now, you must Go To The Source to discover the commands required to manullay intervene in the release process. If something went wrong, then a patch must be developed to fix the problem, so that visit cannot be avoided anyway.