Skip to main content

Release Processes

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

warning

All release processes are mainly done by ATLAS team.

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, the AppIcon component doesn't show a placeholder image if the actual icon is unavailable

Preparing a release​

To prepare a release of the component library ensure the following:

  • ✅ 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 master are green
  • ✅ Make sure to update the test coverage badge. For this, run the follwing commands:
    • yarn test:coverage
    • yarn make-coverage-badges
    • Make sure everything is ok and if so, commit to the release pull request
  • ✅ 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 current date
    • Double-check that all tickets that are slated for release are listed (including their ticket numbers)
    • 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)

Once your release is ready to be reviewed do the following:

  • Create a branch: release-vX.Y.Z(example: release-v1.0.1)
  • Open a pull request and add your team mates as reviewers
  • Merge the branch release-vX.Y.Z once it has approvals

Releasing​

The release of the component library is automated through a GitHub Actions workflow. To trigger the workflow a new git tag has to be added on master.

The workflow will

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

To trigger the release workflow:

  • Create a git tag with: git tag @adjust/components@vX.Y.Z
  • Push the new tag with git push origin --tags

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