A Tag Release Process I Endorse (with CHANGELOG)#
This article is just a personal project record, aimed at systematizing and standardizing the release process to avoid improvisation during each release.
The core principle is just one sentence:
All changes related to the release must be completed in a Release PR,
Tags and Releases can only occur after the PR is merged.
1. Create a release branch#
git checkout -b release/v0.1.0
Each release starts from a separate release branch.
2. Update CHANGELOG.md first#
Add a new version block in CHANGELOG.md to organize all changes for this release.
## [0.1.0] - YYYY-MM-DD
### Added
- ...
### Fixed
- ...
### Changed
- ...
CHANGELOG is the only authoritative source of release content.
3. Update the version number#
Modify the version number in package.json (synchronize lockfile if necessary).
{
"version": "0.1.0"
}
At this stage, do not create a tag.
4. Commit all release preparations at once#
git add CHANGELOG.md package.json package-lock.json
git commit -m "chore(release): prepare v0.1.0"
The version number and CHANGELOG must be submitted together and cannot be separated.
5. Create a Release PR#
git push -u origin release/v0.1.0
gh pr create \
--title "chore(release): v0.1.0" \
--body "Release preparation for v0.1.0"
The Release PR should only contain release-related content:
- CHANGELOG updates
- Version number updates
- CI validation results
6. Merge the Release PR#
After review is complete, merge the Release PR into main.
gh pr merge --merge
Tags are not allowed to be created before this.
7. Create a tag on main#
git checkout main
git pull origin main
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0
The tag points to the final state that has been reviewed and merged.
8. Generate GitHub Release from CHANGELOG#
When publishing the GitHub Release, directly use the content corresponding to the version in CHANGELOG.
gh release create v0.1.0 \
--title "v0.1.0" \
--notes-file <(extract_changelog_section v0.1.0)
Do not manually write Release Notes to avoid inconsistencies with CHANGELOG.
Conclusion#
This process does not pursue "the fastest" or "most automated."
Its goal is singular:
To make the release process a set of repeatable, traceable, and error-resistant fixed actions.