Automate Versioning and Releases

Setting Up a New Repository

Convert develop to master branch

1. Delete master branch
2. Rename develop branch to master

Environmental Variables

In https://travis-ci.org/SAP/your-repo/settings, add:

• GH_TOKEN (from fundamental-bot - https://github.com/settings/tokens)
• AUTH_TOKEN (from npmjs.com)
• NPM_EMAIL
• NPM_PASSWORD
• NPM_USERNAME

NOTE: Remember to escape special characters.

System/Automated User Setup

• Log into fundamental-bot and sign CLA for the repo you will be pushing to.
• Add fundamental-bot to your team.

Repository Settings

IMPORTANT: Add fundamental-bot as an admin.

Settings

Branch Protection Rules

1. Require pull request reviews before merging
2. Require status checks to pass - Travis CI & CLA
3. Restrict who can push to matching branches (add team here)

Code Changes

.travis.yml

NOTE: Change the first job/stage to whatever the repo specifically needs in way of linting and testing.

ci-scripts/publish.sh

ci-scripts/publish_release.sh

ci-scripts/setup_npm.sh

ci-scripts/create-release.js

ci-scripts/release-notes.js

package.json

1. Add:

   "bin": {
       "create-release": "ci-scripts/create-release.js"
   },
   

2. Add to "scripts":

   "release": "./ci-scripts/publish_release.sh",
   "release:create": "./ci-scripts/create-release.js",
   "std-version": "standard-version -m \"chore(release): version %s build ${TRAVIS_BUILD_NUMBER} [ci skip]\"",
   

Install dev dependencies:

npm i -D standard-version github-api yargs

Usage

Current Version

The current release is where most changes will occur. This will include features, fixes, chores and breaking changes. All merges to master will generate a release candidate (rc) version. Breaking changes need to be handled in a specific way when merging the pull request. See Generate a Breaking Change Release. These "rc" versions will accumulate until a major release cycle when the non-rc version will be released. See Publishing Releases.

Generate a Breaking Change Release on the master Branch

1. Create a branch from master locally
2. Make necessary code changes
3. Commit changes and push branch to GitHub
4. Create a pull request
5. Merge pull request and add BREAKING CHANGE: Version <major-version-number> in the description of the merge message.

NOTE: The key to the breaking change is BREAKING CHANGE: (colon included) in the description (not title) of the merge message.

Publishing Releases

1. Checkout either the master or archive-v# branch locally that you wish to release from.
2. Run the following command to start the release process:

   npm run release
   

This will kick off Travis to run standard-version, updating the version to a non-"rc" version, push the changes and the new tag and publish the package to npm and github pages when it's complete.

NOTE: Publishing releases can only be done from master and archive-v# branches that currently have an "rc" version.

Creating an Archive Branch (Past Version)

NOTE: Only create archive branches once a new breaking change release has been created on master.

Create Branch

1. On GitHub, look up the latest release from the previous major version and make a note of the tag associated with it.
2. Checkout the tag locally

   git checkout <tag-name>
   

3. Create the archive branch

   git checkout -b archive-v<previous-major-version>        # Example: archive-v3
   

4. Make a small change to README.md (add blank line, remove extra blank line, etc.)
5. Commit change and make sure to include [ci skip] in commit message
6. Push branch

   git push --set-upstream origin <archive-branch>
   

Protect Branch

1. Go to the repository on GitHub
2. Select Settings tab
3. Select Branches
4. Under Branch protection rules, select the new branch that was pushed (archive-v#)
5. Select the appropriate options (use master branch as a template) and save the changes