Skip to main content

Version management principles

In the world of software management there exists a dreaded place called “dependency hell.” The bigger your system grows and the more packages you integrate into your software, the more likely you are to find yourself, one day, in this pit of despair.

— Excerpt from the Semantic versioning 2.0.0 specifications

It is crucial we embrace robust version management practices to help our consumers understand:

  • what is available in a specific version
  • what could happen if they upgrade to a newer version

This page describes the high-level principles and practices we follow for every asset in Quartz.

Vertical versioning​

We place utmost importance on keeping our assets perfectly aligned between design, dev, and documentation. We call this Vertical versioning.

This includes the version number, which represent a specific point in time that all team members can refer to, knowing they talk about the same state of the asset.

To help with that, Quartz embraces the Semantic versioning 2.0 specification. This decision has two practical implications on your work:

  • you must understand and follow the rules for labeling and describing the changes you have made to an asset
  • you must release all assets in sync under the same version label: Figma library, code library and documentation updates.

That's why we have a strict release process that is described further below.

Semantic versioning in a nutshell​

Semantic versioning proposes a simple set of rules and requirements that dictate how version numbers are assigned and incremented. [...]

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes
  • MINOR version when you add functionality in a backward compatible manner
  • PATCH version when you make backward compatible bug fixes

— Excerpt from the Semantic versioning 2.0.0 specifications

Our beta releases adds the -beta.NUMBER suffix to the upcoming version number. For example, if the current version is 1.2.5, the next beta version will be:

  • 1.2.6-beta.1 if the change is a bug fix
  • 1.3.0-beta.1 if the change is new feature
  • 2.0.0-beta.1 if the change is not backward-compatible

Contribution lifecycle​

All contributions follow a similar high-level lifecycle:

  1. Make a private copy of the current state of the asset, in the form of so-called branches
  2. Make changes in your branch, which prevents you from breaking the production asset
  3. Submit a request to merge your changes, that will be reviewed and approved by the asset owners
  4. The owners then release a new version of the asset

Depending on the nature of the asset, these steps may vary. They're described in depth in the Versioning pages of the Designing for Quartz and Developing for Quartz sections.

Making a release​

We use the Semantic release software to automate and standardize the release of code assets. One of its key features is to automatically determine the correct version number to apply, ensuring the [semantic versioning 2.0] rules are followed.

That's why all vertical releases must follow these steps in order:

  1. Release the code library. This process will determine the actual version number of the release that will be used in the following steps.
  2. Release the Figma assets with that version number
  3. Release the documentation update with that version number
  4. Announce the release to our community
Last updated on