Skip to main content

Release Processes

This document is a guideline for publishing a new version in ATLAS project.

Component Library​

Versioning schema​

The component library follows the SemVer versioning scheme.

In brief, given a version number MAJOR.MINOR.PATCH we increment as such:

  • MAJOR Breaking API changes.
    • Examples: dark-mode support is deprecated, the iconOnly property of the Button component was removed, the icon Megafon is now called Megaphone
  • MINOR Added functionality that is backward compatible.
    • Examples: a new component is introduced, additional icons are added to the Icon component, the ActionMenu component now support sub menus
  • PATCH Bug fixes that are backward compatible.
    • Examples: Tooltips don't disappear in certain cases, the label of the Badge component is shifted in Firefox

Releasing​

The release of the component library is fully automated through Github Actions.

info

The release workflow is triggered automatically when a PR is merged to the master branch.

Make sure you follow this checklist before merging the PR to the master branch:

  • The version number of the component library has been updated (see Versioning schema)
  • The dependency to the component library in Docusaurus has been updated (see here)
  • All pipeline checks on your PR are green
  • Make sure to check all tests are green
  • If applicable, the newest version of the design-tokens package has been released. More on this here.
  • The release notes have been updated:
    • Add the new component library version and fill in the actual release date
    • Double-check that ticket ID is mentioned in the release notes
    • If the release includes API changes include migration instructions with examples (example)
    • If we can already anticipate a bigger API change or deprecation in the codebase for the following release, mention it. Only do this if we can already give instructions on how to prepare for the next release. (example: deprecation of dark-mode support)

The release workflow will:

  • Publish a new version of the component library via yarn publish
  • Update the component documentation website
  • Create a release on GitHub

After releasing a new version of the component library write is message to the #atlas_design_system channel. Include links to the relevant release notes in your message.

Rolling back a release​

If you notice that something went wrong with the release and you have to un-do it do the following:

  • Remove the tag locally: git tag -d @adjust/components@vX.Y.Z
  • Remove the tag on the remote: git push origin --delete @adjust/components@vX.Y.Z
  • Remove related releases which created on GitHub
  • Remove the newest version of the component library on GitHub packages. You can do this in the package settings under Manage versions
  • Update the documentation website using the publish-documentation action

Design Token Library​

Versioning schema​

The design token library follows the SemVer versioning scheme.

In brief, given a version number MAJOR.MINOR.PATCH we increment as such:

  • MAJOR Breaking API changes.
    • Examples: Added new token to the design token library or exisiting design token is renamed.
  • MINOR
    • Examples: Changed value of existing token. E.g. $border-radius-small: 4px changed to $border-radius-small: 3px
  • PATCH You can leave this always 0 As we don't have changes at this level.

Preparing a release​

Make sure that the following points are covered.

  • ✅ Design tokens are built
  • ✅ The release notes have been updated with the correct date and all relevant changes are listed
  • ✅ The design token version has been bumped according to the versioning schema (see here)
  • ✅ The dependency to the design-token package in the components and docusaurus packages has been updated
  • ✅ Your changes have been tested, merged to master and all pipelines are green

Releasing​

The release is done manually by running yarn publish in packages/design-tokens directory. Or yarn workspace @adjust/design-tokens publish from the root of Atlas.

If you have trouble with authentication check the GitHub documentation for GitHub packages.

If necessary, update the documentation website using the publish-documentation action.

Rolling back a release​

If you notice that something went wrong with the release and you have to un-do it, remove the newest version of the design token library on GitHub packages. You can do this in the "package settings" under Manage versions