Automate Versioning and Releases

Setting Up a New Repository

Convert develop to master branch

1. Remove branch protection from master
2. Delete master branch
3. Rename develop branch to master
4. Setup branch protections for master and gh-pages and make master default branch

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)

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

Code Changes

.travis.yml

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

scripts/publish-release.sh

ci-scripts/setup-npm.sh

ci-scripts/publish.sh

package.json

1. Add to "scripts":

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

Install Dependencies

npm i -D standard-version github-assistant

Usage

Current Version

The current release (master branch) 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. These "rc" versions will accumulate until a release is published. See Publishing Releases. Breaking changes need to be handled in a specific way when merging the pull request. See Generate a Breaking Change Release.

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. The title will still contain the appropriate fix: or feat: prefix.

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