Versioning Your Workspace

In this article, we'll cover multiple ways of versioning your design system:

Versioning using commitizen

NOTE: Most Knapsack workspaces launched before April 2021 utilize commitizen for triggering version releases. If your workspace does not publish npm packages currently, you are likely using this setup.

Commitizen provides git users the ability to denote the type of change being (minor, patch, chore, etc) by prepending the commit message (title in GitHub UI) with one of the following:

  1. feat: commit message here (bumps the workspace by a minor version)
  2. fix: commit message here (bumps the workspace by a patch version)
  3. chore: commit message here (makes no change to the version)

Other options are also available:

View commitizen documentation for more information.

Code Commit + Version Release Process Using Commitizen

  1. Pull down a fresh copy of your workspace's main branch
  2. Branch off the main branch — likely using the feature/[name-of-thing] format
  3. Make desired changes to design system
  4. Commit changes and push!
  5. Create a new PR back into main
  6. In GitHub — Wait for all the tests to pass (bottom of the PR) AND review the staged link provided by CI (will be auto-generated so you can preview your changes in the cloud before merging)
  7. IMPORTANT: Before merging your code — you will need to adjust the title of your commit to include either fix: ... , feat: ..., or chore: ... (as shown above). Only when one of these classifiers are prepended to the commit message will the system know how to handle the change when merged.

Versioning using Git Auto Commit

NOTE: Beginning in April 2021, Knapsack is moving to an automatic method for publishing releases using Git Auto Commit. If your workspace currently publishes npm packages, you are likely using this setup.

Git Auto Commit provides users the ability to use GitHub tags within a PR to denote the type of change we're making (minor, patch, etc.).

Code Commit + Version Release Process Using Git Auto Commit

  1. Pull down a fresh copy of your workspace's main branch
  2. Branch off the main branch — likely using the feature/[name-of-thing] format
  3. Make desired changes to design system
  4. Commit changes and push!
  5. Create a new PR back into main
  6. In GitHub — Wait for all the tests to pass (bottom of the PR) AND review the staged link provided by CI (will be auto-generated so you can preview your changes in the cloud before merging)
  7. IMPORTANT: Before merging your code — make sure to add the proper label (minor, patch, etc) so that Auto knows how to version. Once you've added the label — go ahead and merge!
  8. When the merge/release completes — the PR will automatically receive a "released" label, so you know the PR was released.

What to do when you need CI to release a new version manually

This can happen when a merge takes place without the correct identifier that denotes a change to the system. In this case, we need to perform a manual "bump":

  1. Switch back to the main branch and do a pull
  2. Edit the README.md file with something very simple (can even be an extra line)
  3. For workspaces using Commitizen —> commit with git commit -m "fix: bump ci version" and then push
    For workspaces using Auto —> just commit with whatever message makes most sense (auto will detect this as a minor version bump — if you prefer the patch version you should create a new branch and mark the PR as such before merging into main)
  4. Push your changes and CI should then see the new identifier and will release a new minor version 🎉

Related Articles