Release versioning
Release versioning
Testers, release managers and business owners talk about the same release from the first test campaign until production: each deployment to a versioned major branch creates a semver tag on the deployed commit.
- UAT and preprod get release candidates:
v1.5.0-rc.1,v1.5.0-rc.2,v1.5.0-rc.3, or names in your own format (v1.5.0-pi2-it4-uat-rc1) - Production gets the plain version:
v1.5.0, with a GitHub or GitLab Release holding its release notes
The version shows in the Pull Request comment of the deployment, in the deployment notification, on the branches and orgs of the VS Code DevOps Pipeline and, if you ask for it, on the tickets.
- Activate it
- How a version is chosen
- Tag format of release candidates
- Permissions of the CI/CD jobs
- Releases and release notes
- Versions on tickets (optional)
- See the versions
- Limits
Activate it
Declare releaseVersioning: true in the branch config of each major branch that handles versions. Branches that do not declare it (an integration branch, for example) keep working as before and get no version.
# config/branches/.sfdx-hardis.uat.yml
releaseVersioning: true
# config/branches/.sfdx-hardis.preprod.yml
releaseVersioning: true
# config/branches/.sfdx-hardis.main.yml
releaseVersioning: true
The order of the branches comes from their mergeTargets. The highest versioned branch of the chain (usually main) gets plain versions, every other versioned branch gets release candidates.
Optional settings, in config/.sfdx-hardis.yml:
| Setting | Default | Use |
|---|---|---|
releaseVersioningInitialVersion |
1.0.0 |
First version when the repository has no semver tag. A repository that already has tags (v1.3.0 or 1.3.0) carries on from the highest one. |
releaseVersioningMinimumVersion |
Set it to 2.0.0 to start a major version. A computed version below it is raised to it. Once that version exists, the setting has no more effect. |
|
releaseVersioningTicketVersions |
none |
Write the versions on tickets: allCandidates or finalOnly. See Versions on tickets. |
releaseVersioningTagFormat and releaseVersioningMinimumVariables name the release candidates: see Tag format of release candidates.
Then give the deployment jobs the permissions they need.
How a version is chosen
The version only depends on the existing tags, on the branch deployed, and on where its Pull Request comes from. No version file is committed: there is nothing to merge or to keep in sync between branches.
A release cycle on a pipeline int -> uat -> preprod -> main, where uat, preprod and main declare releaseVersioning: true, after v1.3.0:
| Deployment | Version | Why |
|---|---|---|
| int promoted to uat | v1.4.0-rc.1 |
The first deployment to uat after v1.3.0 opens release 1.4.0 |
| int promoted to uat again | v1.4.0-rc.2 |
Same release, next release candidate |
| uat promoted to preprod | v1.4.0-rc.3 |
uat and preprod have the same tag format: they share one counter |
| int promoted to uat | v1.5.0-rc.1 |
Release 1.4.0 moved up to preprod: uat opens the next one |
| preprod promoted to main | v1.4.0 |
Production gets the plain version of the release it receives |
| hotfix merged into preprod | v1.4.1-rc.1 |
Nothing waits in preprod for production: the hotfix starts a patch |
| preprod promoted to main | v1.4.1 |
|
| hotfix backpromoted to uat, with new work | v1.5.0-rc.2 |
Release 1.5.0 is still in uat |
| uat promoted to preprod | v1.5.0-rc.3 |
|
| int promoted to uat | v1.6.0-rc.1 |
Release 1.5.0 moved up: uat opens release 1.6.0 |
The rules behind it:
- Lowest versioned branch (uat): it adds release candidates to its open release until a tag of that release exists on a higher branch, or the release is in production. The next deployment then opens the next minor version.
- Middle branches (preprod): a promotion from the branch below (or a promotion branch built from it) takes the version coming up. Anything else is a hotfix, including a higher branch merged back into it: it joins the release waiting there for production, or starts the next patch of production when nothing waits.
- Highest versioned branch (main): it gets the plain version of the newest release candidate reachable from the deployed commit and not released yet. A promotion branch cherry-picks its User Stories, so nothing of its source is reachable: it gets the version last deployed on that source. When a release overtook another one in preprod, only the newest is released, and its release notes start from the previous production version. When no release candidate waits (a fix merged straight into main), it gets the next patch of production:
v1.3.1afterv1.3.0. - A single versioned branch: every deployment is a release, and gets the next minor version.
- Major versions: set
releaseVersioningMinimumVersion: 2.0.0. - A deployment job run again on a commit that already has its version tag creates no new tag. On the highest versioned branch, it publishes the Release only when the first run could not create it.
- A shallow clone (the default of GitLab CI) is completed with its history first, so the release candidates older than the clone depth are found.
- When the tag name is already taken (two jobs computing the same version at the same time, or a tag created by hand with that name), the git provider refuses it and the job takes the next release candidate.
Each tag is an annotated tag whose message says which branch and which org it was deployed to, when, from which Pull Request and by which job, with its version, release candidate number and variables. Tags created by hand count for the numbering, without a branch, when their name is a plain semver version (v1.3.0, v1.3.0-rc.2).
Tag format of release candidates
By default, release candidates are named v{MAJ}.{MIN}.{PATCH}-rc.{RC}. Set releaseVersioningTagFormat to name them your own way: in config/.sfdx-hardis.yml for every versioned branch, or in the config of one branch for that branch only.
# config/branches/.sfdx-hardis.uat.yml
releaseVersioning: true
releaseVersioningTagFormat: v{MAJ}.{MIN}.{PATCH}-pi{PI}-it{IT}-{BRANCH}-rc{RC}
releaseVersioningMinimumVariables:
PI: 2
IT: 4
# config/branches/.sfdx-hardis.preprod.yml
releaseVersioning: true
releaseVersioningTagFormat: v{MAJ}.{MIN}.{PATCH}-{BRANCH}-rc{RC}
# config/branches/.sfdx-hardis.main.yml
releaseVersioning: true
| Placeholder | Value |
|---|---|
{MAJ}, {MIN}, {PATCH} |
The version, chosen by the rules above. Required. |
{RC} |
The release candidate number. Required. |
{BRANCH} |
The git branch name, / and any character a tag cannot hold written -: release/uat gives release-uat. Use it rather than writing the branch name in the format: one format then serves several branches, each with its own counter. |
Any other {NAME} ({PI}...) |
A custom variable, from releaseVersioningMinimumVariables and the previous tags. Its name holds letters and digits only. |
Use case: program increments and iterations
A team plans its work in program increments (PI) of several iterations (IT), and its testers want to read the PI and the iteration in the name of each UAT release candidate. With the config above, and no tag at the start:
| Deployment | Tag | Why |
|---|---|---|
| int promoted to uat | v1.0.0-pi2-it4-uat-rc1 |
First release, PI 2 and IT 4 from the config |
int promoted to uat, once v1.0.0-pi2-it4-uat-rc2 was created by hand |
v1.0.0-pi2-it4-uat-rc3 |
The name is taken: the job takes the next release candidate |
| uat promoted to preprod | v1.0.0-preprod-rc1 |
Another text: its own counter starts at 1 |
A Pull Request sets IT: 5 in config/.sfdx-hardis.yml, int promoted to uat |
v1.1.0-pi2-it5-uat-rc1 |
1.0.0 moved up to preprod: uat opens 1.1.0, with the IT the Pull Request brought |
| hotfix merged into preprod | v1.0.0-preprod-rc2 |
The hotfix joins the release waiting in preprod |
| preprod promoted to main | v1.0.0 |
Production gets the plain version, and a Release listing the Pull Requests of 1.0.0 |
A new PI starts: CI/CD variables ..._VAR_PI=3 and ..._VAR_IT=1, int promoted to uat |
v1.1.0-pi3-it1-uat-rc1 |
No Pull Request needed. PI 3 / IT 1 is above PI 2 / IT 5. A new text: the counter restarts |
Only uat moves to the next iteration: ..._VAR_UAT_IT=2, int promoted to uat |
v1.1.0-pi3-it2-uat-rc1 |
The variable of one branch wins over the variable of every branch |
..._VAR_UAT_IT=1, int promoted to uat |
v1.1.0-pi3-it2-uat-rc2 |
A value is a minimum: the tags hold IT 2 already, lowering it has no effect |
..._TAG_FORMAT=v{MAJ}.{MIN}.{PATCH}-{BRANCH}-rc.{RC}, int promoted to uat |
v1.1.0-uat-rc.1 |
One format for every branch, from the CI/CD server. A new text: the counter restarts |
| That variable removed, uat promoted to preprod | v1.1.0-preprod-rc1 |
preprod uses its own format again |
| preprod promoted to main | v1.1.0 |
Its release notes start from v1.0.0 |
The CI/CD variables are listed in the rules below. MIN only goes up once, when uat opens 1.1.0: production takes the version of the release candidate it receives, and a hotfix joins the release waiting in preprod.
The rules:
- The format:
{MAJ},{MIN},{PATCH}and{RC}once each, two placeholders never side by side, custom variable names of letters and digits only (no_:..._VAR_UAT_PIthen always means{PI}of the branch uat), and only letters, digits,.,_and-around them, so the name is a valid git tag, JIRA fix version and ticket label. An invalid format logs a warning and the branch uses the default one: it never fails a deployment. - One counter per tag text: the next release candidate is 1 + the highest one among the tags of the same version with the same text around
{RC}. A new PI, a new iteration or another branch gives a new text, and its counter starts at 1. Two branches with the same format share one counter, so their tags never collide. Changing the format also restarts the counter. - Variables never change on their own: a tag takes the values of the previous tags. They change when a Pull Request raises
releaseVersioningMinimumVariables, and the next tag takes the new values. They compare together, in the order of the format, like a semver: PI 3 / IT 1 is above PI 2 / IT 5. A value set in a branch config replaces the project value of the same variable. - A variable with no value, neither in the previous tags nor in the config: warning, no tag, and the deployment goes on.
- Production (the highest versioned branch) always gets
v1.5.0: a format set in its branch config is ignored, with a warning. - CI/CD variables override the config, for example to start a new PI without a Pull Request:
Variable Overrides SFDX_HARDIS_RELEASE_VERSIONING_TAG_FORMATreleaseVersioningTagFormatof every versioned branch but productionSFDX_HARDIS_RELEASE_VERSIONING_VAR_<NAME>The value of {NAME}inreleaseVersioningMinimumVariables, for every branch:..._VAR_PI=3SFDX_HARDIS_RELEASE_VERSIONING_VAR_<BRANCH>_<NAME>The same for one branch, over the previous one: ..._VAR_UAT_IT=1.release/uatis writtenRELEASE_UATGitLab, Azure Pipelines and Bitbucket Pipelines give their variables to every job. GitHub Actions does not: map each repository variable in the
envof the deployment step of.github/workflows/process-deploy.yml, likeSFDX_HARDIS_RELEASE_VERSIONING_VAR_PI: ${{ vars.SFDX_HARDIS_RELEASE_VERSIONING_VAR_PI }}(the template has commented examples).A variable value is still a minimum: the tags win when they hold higher values, and lowering it has no effect. Set every variable that changes (
PIandITfor a new PI), not only the first one. The DevOps Pipeline of VS Code computes the next versions on your computer, without the variables of your CI/CD server. - sfdx-hardis never reads a version from a custom tag name: the version, the release candidate number and the variables are written in the message of each tag, and read from there. A tag created by hand counts only when its name is a plain semver version.
Permissions of the CI/CD jobs
Tags and Releases are created through the API of the git provider, with the token sfdx-hardis already uses for Pull Request comments: the job never pushes. The token needs one more permission.
| Git provider | Tag | Release at production | What to change |
|---|---|---|---|
| GitHub | Git refs API | GitHub Release, PDF and XLSX attached | In .github/workflows/process-deploy.yml, replace contents: read by contents: write |
| GitLab | Repository tags API | GitLab Release, PDF and XLSX as release links | CI_SFDX_HARDIS_GITLAB_TOKEN with the api scope; the Maintainer role when v* tags are protected |
| Azure DevOps | Annotated tags API | No Release object: the release notes stay in the artifacts of the job | Give the Build Service the Create tag permission on the repository |
| Bitbucket Cloud | Refs tags API | No Release object: the release notes stay in the artifacts of the job | CI_SFDX_HARDIS_BITBUCKET_TOKEN with the repository:write scope |
Jenkins and the other CI servers use the git provider of the repository.
A missing permission never fails the deployment: the metadata is already in the org. The job logs a warning and the deployment goes on without a version.
Releases and release notes
When the deployment to the highest versioned branch succeeds, the job runs hardis:doc:release-notes for the new version, then creates the Release:
- the Markdown of the release notes is the body of the Release
- the PDF and the XLSX are attached
- the release notes cover the previous production version to the new one:
v1.4.1tov1.5.0, never one of its own release candidates. They list the Pull Requests of the release: its User Stories, its hotfixes and the promotion to production - the release notes notification (Slack, Teams, email...) is sent once the Release exists: its summary, the PDF and the XLSX, and a View Release button
If the release notes cannot be generated, the Release is still created, with a link to the comparison between the two versions and to the job.
The release notes of any version can also be generated by hand: sf hardis:doc:release-notes --mode post --release-tag v1.5.0-rc.3. A release candidate starts from the version deployed on its own branch just before it.
Versions on tickets (optional)
Off by default. With releaseVersioningTicketVersions, the tickets referenced by the deployed Pull Requests get the version:
| Value | UAT and preprod | main |
|---|---|---|
none |
Nothing | Nothing |
allCandidates |
Each release candidate: v1.5.0-rc.2, v1.5.0-rc.3 |
v1.5.0 |
finalOnly |
Nothing | v1.5.0 |
- JIRA: a fix version of the project of the ticket, created when missing, and marked released with the date of the day when main is deployed. With
allCandidates, the release candidates also appear in the release list of the project. - ServiceNow, Aha!, Azure Boards: a label or a tag on the record.
See the versions
- Pull Request comment of the deployment:
Release version: v1.5.0-rc.3, linked to the tag. - Deployment notification (Slack, Teams, email...): the same line, for every versioned deployment, release candidates included.
- Release notes notification: for each production version, with the release notes files and a link to the Release.
- VS Code DevOps Pipeline: a Versions button, off by default and remembered in the extension settings, shows the version deployed under each versioned branch and org and the version each promotion will create under its Pull Request. A Releases tab lists the versions. They are read only when you turn the button on or open a tab that shows them, so they never slow down the pipeline. A click on the version of a branch opens its history and its release notes.
- Command line: hardis:project:version:list lists the version of each branch, the version each promotion would create, and the history of the version tags.
sf hardis:project:version:list
sf hardis:project:version:list --json
Limits
- Versions are created by CI/CD jobs only: a deployment run from a computer creates no tag and no Release.
- Projects that deploy before the merge (deploy before merge mode) get no version: the deployed commit is not on the branch yet.
- Azure DevOps and Bitbucket have no Release object: the version is a tag, and the release notes stay in the artifacts of the job.
- Two branches merged into the same one (uat and uatrun into preprod) can open two releases at the same time.
- Tags created by hand in a custom format (
v1.5.0-pi2-rc1) are not read: only plain semver names count. - In the JSON of
hardis:project:version:list,versionis the semver form (1.5.0-rc.1): with tag formats, two release candidates of two branches can share it.tagis the name to rely on.