Skip to content

Release workflow

Jump to bottom
colbytcook edited this page Jul 26, 2022 · 32 revisions

Creating releases

Hotfix release (patch)

  • Create a hotfix/* branch from the head of release/4.x (or the latest release/* branch)
  • Create a PR with this branch merging back into release/4.x.
  • Ensure the label version: patch is on the PR (this should be applied automatically).
  • Merge the PR to trigger the release
  • After the release is complete, merge release/4.x back into master and complete other post release steps

Standard release (minor)

  • Create a PR that merges master into release/4.x
  • Add the label version: minor (IMPORTANT-- if you forget, the release will be a patch release)
  • Merge the PR to trigger the release
  • After the release is complete, merge release/4.x back into master and complete other post release steps

Backwards-breaking release (major)

  • Starting on the previous release branch, create a new branch for the major release (e.g. release/4.x if the last release was 3.x)
  • Before you are ready to release, you may merge into this branch as much as you want without triggering a release.
  • When you're ready to release:
    • On this branch, update the conditions in the 'Full Release' line in .travis.yml to include your new major release: e.g. if: (branch =~ /(release)\/[1-3]/) -> if: (branch =~ /(release)\/[1-4]/)
    • Add the label version: major to a PR from master into this branch
    • Marge the PR to trigger the release
  • Update the default branch in Github to be release/4.x (or whatever your release is)

Post-release steps

  • The PHP projects on packagist.org (core-php and bolt_connect) don't update by themselves, but instead required you to click the 'Update' button after a release to fetch new versions.
  • Perform the Drupal steps in Gitlab to make the release available to Drupal.
  • Merge the release branch back into master
  • Update the latest release in the description for the ds-dev-help Slack channel
  • Send an email to the QA and UX team and other team leads describing any visual changes. See the post-release email template for more detail.

Special cases

Canary release

Canary releases can be made by adding a simple git tag to any commit on any branch (e.g. v2.10.0-my-canary). This is enough to pull in a canary release on Drupal. For Drupal's build processes, the tag name must begin with a valid semver number, e.g. v2.10.0. It can end with anything you want, e.g -my-canary.

Hotfix a release that's not the latest

Normally, hotfixes should be made to the latest release and sites experiencing issues should just update to the latest version of Bolt. However, sometimes a site can't update to the latest release immediately (for example, if they're very near a release of their own and don't want to introduce last minute bugs). In this case, you can hotfix a previous tag with the following steps:

  • Find the tag of the release you wish to hotfix.
  • Starting at this tag, create a branch called release/[last-major].[last-minor].x (for example, if you're hotfixing 4.1.1, the branch name would be release/4.1.x). Push this branch without adding any commits to it.
  • Also starting at the tag, create a hotfix/* branch and commit your fix to it.
  • Create a PR merging your new hotfix branch into your new release branch. When merged, it should create a release with the version implemented by one patch from your tag (e.g. if the tag was 4.1.1, the merge will create 4.1.2).
  • Additional hotfix PRs can be made against this same release branch (each merge will create a new release)
  • Merge the release branch back into master to ensure the fix appears in the next standard release.
  • Manually update the version selector cache on master or else you will see a warning on master that the cache is out of date.
    • Run set -o allexport; source .env; set +o allexport (loads your tokens).
    • Then run yarn build to update the .incache file.
    • Commit this change to master with the message [skip travis] chore: update .incache file.

Github labels

Github labels and their affect on releases is as follows:

  • type: labels (type: bugfix, type: feature, type: docs) determine which section of release notes a given PR will be added to. They will be automatically added to PRs based on the branch naming conventions-- no manual step should be necessary.
  • version: labels (version: major, version: minor, version: patch) determine the version bump when creating a PR. See details in the Creating releases section below
  • breaking change is the only label that should be added manually to a normal feature or fix PR. It indicates the PR contains a breaking change and will affect both the release notes and version bump when merged into a release branch.

Extras

Optionally, before a patch, minor, or major release, you can test to see what the release notes will be. Check out the head of the branch you're about to merge, then:

Get the release type:

  • npx version -v --from [previous version]
  • npx version -v --from v2.25.1

Get the release notes:

  • npx auto release --dry-run --from [previous version] --use-version=[release type]
  • npx auto release --dry-run --from v2.25.1 --use-version=minor

Auto-release script

The release process is automated when you follow the steps above. This is what the auto-release script does behind the scenes:

  1. auto gets the next semantic version based on PR labels since last release
  2. Based on next semantic version, update PHP package versions, stage and commit these changes
  3. Reset Git, delete private-key file generated by PHP update step
  4. lerna bumps all packages to the next semantic version, publishes to NPM
  5. auto generates a Git release (not a tag)
  6. .incache is updated with the new release (for version selector)
  7. now aliases boltdesignsystem.com to latest tag-specific url (e.g. https://v3-5-4.boltdesignsystem.com/)
  8. now deploys the HEAD of the current release branch (presumably to boltdesignsystem.com (?))
  9. now aliases branch-specific, tag-specific, and several other domain variations to the latest release url
  10. Commit .incache file
  11. Create a Git tag (e.g. v3.6.0), push it
  12. Reset Git
  13. Announce on Slack
  14. Merge back into master (currently disabled, must do it manually)

Running the release script locally

If something goes wrong with auto-release on Travis, you may have to run the script locally. Be sure you are on the target release/* branch (e.g. release/4.x). Then, do the following:

Setup required tokens

  1. Create an .env file in the root of the repo (it will be git-ignored, DO NOT COMMIT!). Add the following tokens:
export GITHUB_TOKEN=YOUR_TOKEN_HERE
export GH_TOKEN=YOUR_TOKEN_HERE
export NPM_TOKEN=YOUR_TOKEN_HERE
export NOW_TOKEN=YOUR_TOKEN_HERE
  1. Get your tokens:
  1. Run echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/.npmrc (Required by Lerna)

Run it

yarn install --frozen-lockfile
yarn run setup:php
git reset --hard
yarn run release

Did your packages fail to publish to NPM?

If this should happen, usually because of a bad NPM token, you can manually publish like so:

# Make sure you are on the release branch, for example release/5.x
git checkout release/5.x

# Load tokens from .env
set -o allexport; source .env; set +o allexport

# Publish from packages (i.e. any packages that are ahead of what's on NPM)
npx lerna publish from-package

Note: After running the lerna command, you will have a chance to review what packages will be published before it executes. If you are prompted for "OTP", it means you need to setup 2FA.

Drupal Steps

  1. Create a new tag matching the /^v\d+.\d+.\d+(-beta-\d+)?$/ regular expression in https://gitlab.com/pegadigital/bolt/bolt-release-build/-/tags. Use the following steps to do this.
    • From the Tags page click on the "New tag" on the top right.
    • Enter in the desired tag to match the newly create Bolt Github release tag (follow the v#.#.# pattern) (leave the "Create from" select to "master").
  2. Verify that everything goes as expected:

Popular Pages

Clone this wiki locally