Skip to content

Versioning in depth

This section will describe the full version flow to be followed in order to release pre-releases on the @next tag and releases on the @latest tag.

In order to keep our changelogs clean and readable, we move the pre-release notes to CHANGELOG-pre-releases.md when a final release is created. When on a pre-release channel, the logs will appear in the normal CHANGELOG.md file until released.

Diagram Legend

legend

Pre-release flow

The flow below is the main flow that is followed in normal development circumstances. It consists out of 2 major blocks:

  • Feature/Fix Development flow
    • Make the required changes
    • add at least 1 changeset with npm run changeset:add
    • Open a PR to dev using squash to review and merge the changes
  • Once dev is stable and internally tested a pre-release can be prepared
    • Create a new branch from dev
    • run npm run changeset:version to apply the changesets and update package versions
    • Review the changes and commit the version updates
    • Open a PR to dev using squash to review and merge the changes

When the PR with version changes lands, the Build and Publish Packages pipeline will automatically publish new packages and update the CDN.

These versions can be installed using the @next tag in the install command. e.g. npm i @xerius/codey-style@next

pre-release-flow

Internal allowed flow:

DANGER

The below steps are a quicker and more flexible way to handle the pre-release flow. This is only allowed by Codey team members as you need to be aware of the state of all moving code.

Details
  • Feature/Fix Development flow
    • This remains the same. Exceptions for pair programming can be made where you commit directly on dev with all required changes (code + changeset)
  • Creating a prerelease
    • Checkout the latest version of dev.
    • run npm run changeset:version to apply the changesets and update package versions
    • Review the changes and commit them with commit message pre-release directly on dev (or pre-release vue2 on dev-vue2 in case it is a vue2 pre-release).
    • Push changes, this will trigger the required pipelines

Release flow

When a pre-release is ready to be released the following flow applies:

Release the pre-release

  • Create a PR to merge dev into master
  • Create a branch from master
  • Run npm run changeset:pre:exit to exit changesets pre-release mode
  • Run npm run changeset:version to apply the changesets and update package versions
  • Move any pre-release notes from the CHANGELOG.md to the CHANGELOG-pre-releases.md file
  • Review the changes and commit the version updates
  • Open a PR to master using squash to review and merge the changes

When the PR with version changes lands, the Build and Publish Packages pipeline will automatically publish new packages and update the CDN.

This will be available on the @latest tag, which is default when installing a package.

Internal allowed flow:

DANGER

The below steps are a quicker and more flexible way to handle the release flow. This is only allowed by Codey team members as you need to be aware of the state of all moving code.

Details
  • Checkout the lastest version of master & ensure you have the latest changes of dev.
  • When possible, fast-forward master to dev, else preform a merge dev into master locally.
  • Run npm run changeset:pre:exit to exit changesets pre-release mode.
  • Run npm run changeset:version to apply the changesets and update package versions.
  • Move any pre-release notes from the CHANGELOG.md to the CHANGELOG-pre-releases.md file.
  • Review the changes and commit the version updates with commit message release directly on master (or release vue2 on vue2 in case it is a vue2 release).
  • Push changes, this will trigger the required pipelines.

Restart pre-release flow

  • Create a PR to merge master into dev if any changes from master are not present in dev
  • Create a branch from dev
  • Run npm run changeset:pre:enter to enter changesets pre-release mode
  • Commit the changes
  • Open a PR to dev using squash to review and merge the changes

Once the PR lands, dev is setup again to run the Pre-release flow

Internal allowed flow:

DANGER

The below steps are a quicker and more flexible way to handle the restart of the pre-release flow. This is only allowed by Codey team members as you need to be aware of the state of all moving code.

Details
  • Checkout the lastest version of dev & ensure you have the latest changes of master.
  • When possible, fast-forward dev to master, else preform a merge of master into dev locally.
  • Run npm run changeset:pre:enter to enter changesets pre-release mode.
  • Commit changes with message restart pre-release mode directly on dev.
  • Push changes, dev is setup again to run the Pre-release flow.


release-flow

Hotfix flow

In case an urgent fix is made on master and needs to be release without the use of the pre-release tag the following flow applies:

  • Create a branch from master
  • Run npm run changeset:version to apply the changesets and update package versions
  • Review the changes and commit the version updates
  • Open a PR to master using squash to review and merge the changes

When the PR with version changes lands, the Build and Publish Packages pipeline will automatically publish new packages and update the CDN.

Lastly master needs to be merged back to dev using a PR with a merge complete



release-flow

Considerations

Pre-releases should always have a higher level version bump then direct releases from master e.g.

// where x isn't touched by that channel
Pre-release: major.minor.x
release: x.x.Patch

In case this is not respected there is a change you get version conflicts. This can be illustrated with the following example:

On the dev branch a pre-release was started after the release of version 11.0.0 . There have only been some patch fixes.
On master a hotfix was made on version 11.0.0 which created version 11.0.1 as this is always a patch.
When we now exit the pre-release on dev and version, it will also create version 11.0.1 as only patches were made. This conflicts with the current released version.
To solve this, manual intervention is required to merge master into dev and change the pre.json file before trying to release the pre-release. There can be merge conflicts in the referenced package.json dependencies when these fixes reside within the same packages. This can make the merge complex as dependencies need also need te be updated correctly.

Because of this, we advice to ether always do a pre-release to release flow (no hotfix directly on master) or always have a feature before releasing (minor change).

At Codey we choose for the latter when possible.