How to create and publish a release for an open source project
GitHub Releases, release tags, semantic versioning, CHANGELOG generation, npm publish, PyPI publish, automated releases with GitHub Actions, release checklist
Releases Are Promises to Users
A release is not just a version bump. It is a communication to your users: here is what changed, here is how to upgrade. Done well, releases build trust. Done poorly, they cause migration pain.
The Release Checklist
# 1. Bump version
npm version minor
# or manually edit version in pyproject.toml
# 2. Update CHANGELOG.md
## [2.5.0] - 2024-03-15
### Added
- CSV export with progress indicator (#234)
### Fixed
- Null pointer on logout with expired session (#198)
# 3. Push tag
git push origin main --tags
# 4. Create GitHub Release from the tag
# 5. Publish to registry
npm publish
# or
python -m build && twine upload dist/*Automating Releases
Use release-please (Google) or semantic-release to automate version bumping and CHANGELOG generation from Conventional Commits. These tools read your commit history and determine the correct version bump automatically. A GitHub Actions workflow triggers them on push to main.
Never publish a release without confirming CI passes on the release commit. A broken release is worse than a delayed one.
Pre-Release Versions
Before shipping a major release, use pre-release versions to gather early feedback. SemVer supports: 3.0.0-alpha.1, 3.0.0-beta.2, 3.0.0-rc.1. Publish these to npm with a dist-tag: npm publish --tag next. Users who want to test the pre-release install it with npm install yourpackage@next. This avoids polluting the default install channel while still letting early adopters test. Mark pre-releases clearly on GitHub Releases -- check the pre-release checkbox so they do not appear as the latest stable version.