How to use the command standard-version (with examples)

Standard-version is a command-line tool that aims to automate the versioning and changelog generation process by using SemVer (semantic versioning) and Conventional Commits. It simplifies the task of maintaining a changelog and keeping track of version updates by automatically generating version tags and updating the changelog file based on the commit history.

Use case 1: Update the changelog file and tag a release

Code:

standard-version

Motivation:

• This use case is helpful when you want to update the changelog file to include the latest changes and create a new release tag.
• It saves time and effort by automating the process of updating the changelog file and generating release tags based on the conventional commits.

Explanation:

• The command standard-version without any additional arguments will update the changelog file and generate a new version tag based on the latest commits.
• It follows the conventional commit format to determine the type of changes (e.g., feat, fix, chore) and increments the version number accordingly.

Example output:

ℹ Releasing 1.2.3

ℹ Updated package.json version to 1.2.3
ℹ Updated CHANGELOG.md
✔️ Created Git tag: v1.2.3

Use case 2: Tag a release without bumping the version

Code:

standard-version --first-release

Motivation:

• This use case allows you to tag a release without incrementing the version number.
• It is useful when creating the first release of a project or starting a new versioning scheme.

Explanation:

• The --first-release argument instructs standard-version to tag a release without bumping the version number in the changelog file.
• It generates an initial release tag without any version incrementation.

Example output:

ℹ Releasing 1.0.0

ℹ Updated package.json version to 1.0.0
ℹ Updated CHANGELOG.md
✔️ Created Git tag: v1.0.0

Use case 3: Update the changelog and tag an alpha release

Code:

standard-version --prerelease alpha

Motivation:

• Alpha releases are often used to share early versions of software with selected users for testing and feedback.
• This use case allows you to generate changelogs and release tags for alpha versions.

Explanation:

• The --prerelease alpha argument instructs standard-version to update the changelog file and generate a release tag for an alpha version.
• It appends the alpha identifier to the existing version number in the changelog.

Example output:

ℹ Releasing 1.2.3-alpha.0

ℹ Updated package.json version to 1.2.3-alpha.0
ℹ Updated CHANGELOG.md
✔️ Created Git tag: v1.2.3-alpha.0

Use case 4: Update the changelog and tag a specific release type

Code:

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

Motivation:

• This use case is beneficial when you want to release a specific type of update (major, minor, or patch) instead of letting standard-version determine the version update based on conventional commits.
• It allows you to have more control over the versioning process.

Explanation:

• The --release-as argument followed by major, minor, or patch instructs standard-version to update the changelog file and generate a release tag accordingly.
• It overrides the automatic version bumping mechanism based on commit types and forces a particular version update.

Example output (for --release-as minor):

ℹ Releasing 1.3.0

ℹ Updated package.json version to 1.3.0
ℹ Updated CHANGELOG.md
✔️ Created Git tag: v1.3.0

Use case 5: Tag a release, preventing hooks from being verified during the commit step

Code:

standard-version --no-verify

Motivation:

• Hooks are custom scripts or actions triggered at specific points during the commit process.
• This use case is useful when you want to skip hook verification during the commit step while tagging a release.

Explanation:

• The --no-verify argument instructs standard-version to skip the hook verification process.
• It allows you to bypass any custom hooks configured in the project and proceed with the release tag.

Example output:

ℹ Releasing 1.2.3

ℹ Updated package.json version to 1.2.3
ℹ Updated CHANGELOG.md
❌ Skipped hook verification
✔️ Created Git tag: v1.2.3

Use case 6: Tag a release committing all staged changes, not just files affected by standard-version

Code:

standard-version --commit-all

Motivation:

• By default, standard-version only commits the changes in the files modified by the versioning process.
• This use case is beneficial when you want to commit all staged changes, including files not affected by standard-version.

Explanation:

• The --commit-all argument instructs standard-version to commit all staged changes, regardless of whether they are related to the versioning process.
• It includes changes made to any file in the commit.

Example output:

ℹ Releasing 1.2.3

ℹ Updated package.json version to 1.2.3
ℹ Updated CHANGELOG.md
✔️ Created Git tag: v1.2.3
✔️ Committed all staged changes

Use case 7: Update a specific changelog file and tag a release

Code:

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

Motivation:

• Sometimes, projects may have multiple changelog files.
• This use case allows you to specify a particular changelog file to update and generate a release tag.

Explanation:

• The --infile argument followed by the path to the changelog file instructs standard-version to update only that specific file with the latest changes.
• It avoids updating all the changelog files in the project.

Example output:

ℹ Releasing 1.2.3

ℹ Updated package.json version to 1.2.3
ℹ Updated path/to/file.md
✔️ Created Git tag: v1.2.3

Use case 8: Display the release that would be performed without performing them

Code:

standard-version --dry-run

Motivation:

• This use case allows you to preview the release process without making any changes to the project.
• It is helpful for testing and ensuring that the versioning and changelog generation are working as expected.

Explanation:

• The --dry-run argument instructs standard-version to simulate the release process without making any modifications to the project.
• It displays the release version, the updated files, and the generated release tag without actually performing them.

Example output:

⚠️ Dry-run releasing 1.2.3

⚠️ Updated package.json version: 1.2.3
⚠️ Updated CHANGELOG.md
⚠️ Git tag to be created: v1.2.3

Conclusion:

Standard-version is a powerful command-line tool that automates the versioning and changelog generation process. It simplifies the task of maintaining a changelog and updating release tags based on conventional commits. The provided use cases showcase various scenarios where standard-version can be customized and used effectively. By incorporating standard-version into your workflow, you can streamline the versioning process and focus on developing your project.