阅读中文版本

Version Tagging and Changelog Workflow

Decide the semantic version bump from commit history, create a signed tag, and generate a changelog grouped by change type.

Overview

Produce an accurate semantic version tag and human-readable changelog from recorded changes.

This workflow is reusable across teams and environments; adapt the commands to your tooling while keeping the sequence and checkpoints intact.

Environment and prerequisites

• Conventional commit history
• Write access to tags
• A changelog generator or template

Procedure

1. Determine the version bump

Read commit types since the last tag to decide major, minor, or patch.

Expected state: The next version matches the highest-impact change.

2. Generate the changelog

Group commits into features, fixes, and breaking changes with links to issues.

Expected state: A readable changelog drafts the release notes.

3. Create and verify a signed tag

Create an annotated, signed tag and push it, then verify the signature.

Expected state: The tag is signed and verifiable by consumers.

4. Publish notes and link artifacts

Publish the changelog with links to the built artifacts for this version.

Expected state: Consumers can find both the notes and the exact artifacts.

git tag -s v1.9.0 -m 'release v1.9.0'
git verify-tag v1.9.0
git push origin v1.9.0

Verification

Confirm the tag signature verifies, the changelog matches the commit range, and artifact links resolve.

Decision points

Who decides the bump?

• Automated from commit types
• Manual judgement

Recommendation: Automate the default and require human confirmation for breaking changes.

Annotated signed tag or lightweight tag?

• Annotated signed tag
• Lightweight tag

Recommendation: Use annotated signed tags so releases are verifiable and carry metadata.

Common failures

• Guessing the version instead of reading commit types.
• Unsigned tags undermine supply-chain verification.
• Changelogs that omit breaking changes surprise consumers.