Control your workflow with Commands¶
Conventional Commits is an excellent standard, but sometimes it doesn't fit our semantic versioning needs. Let's consider major version zero application development from the Semantic Versioning (SemVer
) 2.0 specification:
Major version zero (0.y.z) is for initial development. Anything MAY change at
any time. The public API SHOULD NOT be considered stable.
Within this workflow, the largest semantic increase would be a minor
increment. Relying purely on the conventional commit standard will not trigger a major increment. As nsv
is SemVer compliant, it too will adhere to this, unless explicitly instructed to do so with a command:
feat!: expose new sorting functionality over API
To enable support for server-side sorting, the existing structure of the request
body has been modified to compartmentalize sorting criteria
nsv: force~major
Commands¶
Commands are defined in the footer of a commit message using the case-insensitive nsv:
prefix. Like conventional commits, it is a simple way of describing semantic versioning intent and is designed to fit seamlessly into any developer's workflow. When searching for commands, nsv
stops at the first one it finds. This is an important distinction between using commands and conventional commits to control SemVer.
Multiple commands can be grouped together to achieve your desired outcome:
- If the existing SemVer was
< 1.0.0
, these commands combined would generate a SemVer of1.0.0-beta.1
. Read on to discover how these commands work.
Forcing a semantic increment¶
The force
command allows a developer to take complete control over the semantic release workflow, ignoring any existing conventional commits. It consists of two parts, a mandatory label force~
, followed by the desired semantic increment:
For simplicity, there is a one-to-one mapping to all SemVer increments:
force~major
force~minor
force~patch
If you need to ignore any previous force commands, a break-glass command exists:
force~ignore
Prerelease support ¶
experimental
The pre
command allows a developer to initiate a semantic prerelease workflow, which isn't possible through conventional commits. It consists of two parts, a mandatory label pre
, followed by an optional prerelease version:
There is a one-to-one mapping to common prerelease labels:
pre~alpha
pre~beta
pre~rc
pre
on its own is equivalent topre~beta
A prerelease version generated by the pre
command follows the SemVer convention of:
The .1
part of the version is automatically incremented by nsv
for each subsequent SemVer prerelease. It is reset when transitioning between prerelease labels.