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
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
usingsquash
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
usingsquash
to review and merge the changes
- Create a new branch from
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

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)
- This remains the same. Exceptions for pair programming can be made where you commit directly on
- 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 (orpre-release vue2
on dev-vue2 in case it is a vue2 pre-release). - Push changes, this will trigger the required pipelines
- Checkout the latest version of
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
intomaster
- 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 theCHANGELOG-pre-releases.md
file - Review the changes and commit the version updates
- Open a PR to
master
usingsquash
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 ofdev
. - When possible,
fast-forward
master
todev
, else preform a mergedev
intomaster
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 theCHANGELOG-pre-releases.md
file. - Review the changes and commit the version updates with commit message
release
directly on master (orrelease 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
intodev
if any changes frommaster
are not present indev
- 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
usingsquash
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 ofmaster
. - When possible,
fast-forward
dev
tomaster
, else preform a merge ofmaster
intodev
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.

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
usingsquash
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

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.