Having a semantically versioned software will help you easily maintain and communicate changes in your software. Doing this is not easy. Even after manually merging the PR, tagging the commit, and pushing the release, you still have to write release notes. There are a lot of different steps, and many are repetitive and take time.
Let’s look at how we can make a more efficient flow and completely automating our release process by plugin semantic versioning into a continuous deployment process.
Semantic versioning
A semantic version is a number that consists of three numbers separated by a period. For example, 1.4.10 is a semantic version. Each of the numbers has a specific meaning.
Major change
The first number is a Major change, meaning it has a breaking change.
Minor change
The second number is a Minor change, meaning it adds functionality.
Patch change
The third number is a Patch change, meaning it includes a bug fix.
It is easier to look at semantic versioning as Breaking . Feature . Fix. It is a more precise way of describing a version number that doesn’t leave any room for interpretation.
Commit format
To make sure that we are releasing the correct version — by correctly incrementing the semantic version number — we need to standardize our commit messages. By having a standardized format for commit messages, we can know when to increment which number and easily generate a release note. We are going to be using the Angular commit message convention, although we can change this later if you prefer something else.
It goes like this:
<header>
<optional body>
<optional footer>Each commit message consists of a header, a body, and a footer.
The commit header
The header is mandatory. It has a special format that includes a type, an optional scope, and a subject.
The header’s type is a mandatory field that tells what impact the commit contents have on the next version. It has to be one of the following types:
- feat: New feature
- fix: Bug fix
- docs: Change to the documentation
- style: Changes that do not affect the meaning of the code (e.g. white-space, formatting, missing semi-colons, etc.)
- refactor: Changes that neither fix a bug nor add a feature
- perf: Change that improves performance
- test: Add missing tests or corrections to existing ones
- chore: Changes to the build process or auxiliary tools and libraries, such as generating documentation
The scope is a grouping property that specifies what subsystem the commit is related to, like an API, or the dashboard of an app, or user accounts, etc. If the commit modifies more than one subsystem, then we can use an asterisk (*) instead.
The header subject should hold a short description of what has been done. There are a few rules when writing one:
- Use the imperative, present tense (e.g. “change” instead of “changed” or “changes”).
- Lowercase the first letter on the first word.
- Leave out a period (
.) at the end. - Avoid writing subjects longer than 80 charactersThe commit body.
Just like the header subject, use the imperative, present tense for the body. It should include the motivation for the change and contrast this with previous behavior.
The commit footer
The footer should contain any information about breaking changes and is also the place to reference issues that this commit closes.
Breaking change information should start with BREAKING CHANGE: followed by a space or two new lines. The rest of the commit message goes here.
Enforcing a commit format
Working on a team is always a challenge when you have to standardize anything that everyone has to conform to. To make sure that everybody uses the same commit standard, we are going to use Commitizen.
Commitizen is a command-line tool that makes it easier to use a consistent commit format. Making a repo Commitizen-friendly means that anyone on the team can run git cz and get a detailed prompt for filling out a commit message.
Generating a release
Now that we know our commits follow a consistent standard, we can work on generating a release and release notes. For this, we will use a package called semantic-release. It is a well-maintained package with great support for multiple continuous integration (CI) platforms.
semantic-release is the key to our journey, as it will perform all the necessary steps to a release, including:
- Figuring out the last version you published
- Determining the type of release based on commits added since the last release
- Generating release notes for commits added since the last release
- Updating a
package.jsonfile and creating a Git tag that corresponds to the new release version - Pushing the new release
Any CI will do. For this article we are using GitHub Action, because I love using a platform’s existing features before reaching for a third-party solution.
There are multiple ways to install semantic-release but we’ll use semantic-release-cli as it provides takes things step-by-step. Let’s run npx semantic-release-cli setup in the terminal, then fill out the interactive wizard.
Th script will do a couple of things:
- It runs
npm adduserwith the NPM information provided to generate a.npmrc. - It creates a GitHub personal token.
- It updates
package.json.
After the CLI finishes, it wil add semantic-release to the package.json but it won’t actually install it. Run npm install to install it as well as other project dependencies.
The only thing left for us is to configure the CI via GitHub Actions. We need to manually add a workflow that will run semantic-release. Let’s create a release workflow in .github/workflows/release.yml.
name: Release
on:
push:
branches:
- main
jobs:
release:
name: Release
runs-on: ubuntu-18.04
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup Node.js
uses: actions/setup-node@v1
with:
node-version: 12
- name: Install dependencies
run: npm ci
- name: Release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# If you need an NPM release, you can add the NPM_TOKEN
# NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
run: npm run releaseSteffen Brewersdorff already does an excellent job covering CI with GitHub Actions, but let’s just briefly go over what’s happening here.
This will wait for the push on the main branch to happen, only then run the pipeline. Feel free to change this to work on one, two, or all branches.
on:
push:
branches:
- mainThen, it pulls the repo with checkout and installs Node so that npm is available to install the project dependencies. A test step could go, if that’s something you prefer.
- name: Checkout
uses: actions/checkout@v2
- name: Setup Node.js
uses: actions/setup-node@v1
with:
node-version: 12
- name: Install dependencies
run: npm ci
# You can add a test step here
# - name: Run Tests
# run: npm testFinally, let semantic-release do all the magic:
- name: Release
run: npm run releasePush the changes and look at the actions:
Now each time a commit is made (or merged) to a specified branch, the action will run and make a release, complete with release notes.
Release party!
We have successfully created a CI/CD semantic release workflow! Not that painful, right? The setup is relatively simple and there are no downsides to having a semantic release workflow. It only makes tracking changes a lot easier.
semantic-release has a lot of plugins that can make an even more advanced automations. For example, there’s even a Slack release bot that can post to a project channel once the project has been successfully deployed. No need to head over to GitHub to find updates!
The post How to Automate Project Versioning and Releases with Continuous Deployment appeared first on CSS-Tricks.
You can support CSS-Tricks by being an MVP Supporter.
