Publishing

How to take your changes into production

This topic is for advanced users who have ownership of the deployment process. If using a P1-managed repository, you will likely not have permission to publish code yourself.

Contact [e-mail] if you're missing permissions!

Versioning your changes

The BaseCMS Website Framework provides several utilities around the versioning and deployment of your code. P1-managed repositories will use the Lerna toolkit to manage versions, and deployments to your production and staging environments are based on the respective semantic version.

Lerna powers the deployment process for monorepos by keeping versions in sync, and bumping package versions when changes are made. If, for example, you have two different websites in one repository, a version change for site #1 would only be made when the files in site #1 change, or when a package the site depends on is updated.

Semantic versioning

In general we follow semantic versioning, which is <MAJOR>.<MINOR>.<PATCH>, with a few suffixes to indicate non-production status such as -alpha.0. With P1-managed repositories, we use the following rules when determining how to version your project:

• Update the major version number when functionality is removed.

• Update the minor version number when new functionality is added.

• Update the patch version number when non-breaking or non-critical changes are made.

In practice, most changes to your site will be patches and major versions are rarely changed.

Installing Lerna

For P1-managed repositories, lerna is already available (assuming you have run the installation command). You can access this through the CLI by running ./scripts/lerna.sh

Lerna can be installed globally on your machine or as a dev-only dependency of your project:

# install globally with yarn
yarn add --global lerna

# install for this project only
yarn add -D lerna

Creating the version

You must have permission to write directly to your repository's master branch in order to use Lerna for versioning. If you have branch protections enabled, you must also have administrative permissions to bypass these protections.

To create a new version, first ensure that you are on the master branch of your repository, your repository is up to date, and that the origin remote is set to your upstream (not a fork!)

# Check out the latest changes on the `master` branch
git checkout master; git fetch; git pull

# Ensure `origin` is not a fork!
git remote -v | grep origin

Once your code is up to date and lerna is installed, you can use the lerna CLI to create a new version. The version type would be one of major, minor, patch, or a pre- variant such as prepatch following the semantic versioning instructions above.

# For P1-managed repositories, use the provided lerna script
./scripts/lerna.sh version <VERSION TYPE>

# Otherwise, use the lerna CLI command directly
lerna version <VERSION TYPE>

Once the Lerna command completes, new versions will be tagged and pushed to GitHub. For P1-managed repositories, these tags will trigger deployments via TravisCI.

You can view the deployment status by visiting your upstream repository's page on TravisCI (travis-ci.com/github/<username-or-organization-name>/<repository-name>/builds), selecting the Build History tab, and then selecting the build that matches your previously published version.

Build status on TravisCI