How to Use the 'standard-version' Command (with Examples)

The standard-version command is a tool that automates versioning and changelog generation based on semantic versioning (SemVer) principles and Conventional Commits specifications. It simplifies the process of managing project versions, making it easier to keep track of changes and expedite release processes by automatically updating version numbers and generating changelogs.

Use Case 1: Update the Changelog File and Tag a Release

Code:

standard-version

Motivation:

The primary motivation for using the standard-version command in its simplest form is to streamline the entire release process. By automatically updating the changelog and tagging a new release, developers can save significant time that would otherwise be spent manually incrementing version numbers and compiling lists of changes. This use case is especially helpful when working in teams or handling larger codebases, where consistent version control is crucial.

Explanation:

• standard-version: When run without arguments, this command scans the commit history for commit messages following the Conventional Commits pattern, determines the next version bump according to SemVer rules, updates the CHANGELOG.md file, commits these changes, and tags a new release in the version control system.

Example Output:

✔ bumping version in package.json from 1.0.0 to 1.1.0
✔ outputting changes to CHANGELOG.md
✔ committing package.json and CHANGELOG.md
✔ tagging release v1.1.0

Use Case 2: Tag a Release Without Bumping the Version

Code:

standard-version --first-release

Motivation:

The --first-release option is ideal for tagging an initial release of a project without incrementing the version number. This is particularly useful when you have an existing codebase you want to release for the first time using standard-version. This ensures that an initial version and changelog are established, allowing for a clean start in version control.

Explanation:

• --first-release: This flag indicates that this is the first time a release is being tagged for the project, thus, no version bump is needed. It serves to establish a 1.0.0 baseline for the project.

Example Output:

✔ outputting changes to CHANGELOG.md
✔ committing CHANGELOG.md
✔ tagging release v1.0.0

Use Case 3: Update the Changelog and Tag an Alpha Release

Code:

standard-version --prerelease alpha

Motivation:

This use case is particularly useful during stages of development where a full stable release is not yet ready, but you want to communicate progress or test the software. By tagging a prerelease, such as an alpha version, you can distribute pre-release software to testing environments or select audiences without affecting users dependent on stable releases.

Explanation:

• --prerelease alpha: The --prerelease flag allows tagging with a custom prerelease identifier. In this case, alpha denotes a developmental release stage that is not intended for production use.

Example Output:

✔ bumping version in package.json from 1.1.0 to 1.1.1-alpha.0
✔ outputting changes to CHANGELOG.md
✔ committing package.json and CHANGELOG.md
✔ tagging release v1.1.1-alpha.0

Use Case 4: Update the Changelog and Tag a Specific Release Type

Code:

standard-version --release-as major|minor|patch

Motivation:

Sometimes, developers need explicit control over the versioning process. The --release-as option allows you to bypass automatic version determination and directly specify a major, minor, or patch release. This is especially useful in situations where the commits may not completely reflect the semantic impact on the versioning system or when integrating major features or bug fixes.

Explanation:

• --release-as major|minor|patch: This option forces the release version to increment in the specified manner (major, minor, or patch), regardless of the commit messages’ implied changes.

Example Output:

✔ bumping version in package.json from 1.1.0 to 2.0.0
✔ outputting changes to CHANGELOG.md
✔ committing package.json and CHANGELOG.md
✔ tagging release v2.0.0

Use Case 5: Tag a Release Preventing Hooks from Being Verified

Code:

standard-version --no-verify

Motivation:

In some cases, pre-commit or other git hooks may interfere with the release process, either by introducing unintended side effects or by failing due to ongoing reconfiguration. The --no-verify flag allows a release to proceed smoothly without executing these hooks, ensuring that the release process is uninterrupted by custom scripts or configurations.

Explanation:

• --no-verify: This argument skips all git hooks during the commit step, thus allowing the process to be minimally obstructive and more straightforward.

Example Output:

✔ bumping version in package.json from 2.0.0 to 2.0.1
✔ outputting changes to CHANGELOG.md
✔ committing package.json and CHANGELOG.md with --no-verify
✔ tagging release v2.0.1

Use Case 6: Tag a Release Committing All Staged Changes

Code:

standard-version --commit-all

Motivation:

The --commit-all flag is advantageous when you have multiple changes staged in your git working directory that aren’t directly managed by standard-version, but you want them included in the commit that tags the release. This ensures that all relevant changes across the project are synchronized with the new version tag, maintaining consistency.

Explanation:

• --commit-all: Causes the command to commit all staged files along with standard-version managed files, ensuring that the release commit reflects the complete set of intended changes.

Example Output:

✔ bumping version in package.json from 2.0.1 to 2.0.2
✔ outputting changes to CHANGELOG.md
✔ committing all staged changes
✔ tagging release v2.0.2

Use Case 7: Update a Specific Changelog File and Tag a Release

Code:

standard-version --infile path/to/file.md

Motivation:

Projects with multiple changelogs for different parts or modules might require a specific file to be updated during the release. The --infile option allows directing the output of the changelog changes to a designated file, thus maintaining the custom documentation structure of the project.

Explanation:

• --infile path/to/file.md: Directs the changelog output to a specific file path, allowing developers to manage and update changelogs according to their project setup.

Example Output:

✔ bumping version in package.json from 2.0.2 to 2.0.3
✔ outputting changes to path/to/file.md
✔ committing package.json and path/to/file.md
✔ tagging release v2.0.3

Use Case 8: Display the Release That Would Be Performed Without Executing It

Code:

standard-version --dry-run

Motivation:

During development or testing phases, it can be beneficial to understand what a release cycle would entail without actually performing changes. The --dry-run option enables developers to preview the impact of a potential release, allowing for corrections or preparations in advance without modifying the repository.

Explanation:

• --dry-run: Simulates the entire release process without applying any changes, providing an overview of the version bump, changelog updates, and commit message that would be executed.

Example Output:

✔ bumping version in package.json from 2.0.3 to 2.0.4
✔ outputting changes to CHANGELOG.md
✔ proposed commit: 2.0.4

Conclusion

The standard-version command provides a comprehensive suite of options to maintain, automate, and streamline the versioning and changelog processes in software projects. Whether you need initial release setup, pre-release versioning, or detailed control over changelog updates, standard-version offers efficient solutions tailored to various development scenarios. By adopting this tool, maintaining adherence to semantic versioning standards becomes an integral yet unobtrusive part of the coding workflow.