How to cut a production release. Each step depends on the previous one, so do them in order.
1. Determine the release number
Versions follow YYYY.M.N: current year, current month (no zero-padding), and an incrementing number for releases within that month. The 3rd release of July 2026 is 2026.7.3.
Find the previous release with git tag --sort=-creatordate | head -5. If the latest tag is from the current month, increment its last number; otherwise start over at .1 for the new month.
2. Tag the release
Tag the commit to be released (normally the tip of main) and push the tag:
git tag 2026.7.3
git push origin 2026.7.3Pushing a *.*.* tag triggers the release workflows (Release - Desktop App, Release - Docker Images). The Docker workflow ends by publishing the released hypermedia/ tree to the developer docs site on hyper.media (Repo HM sync (hypermedia), target production, signed with the SEED_DOCS_KEYFILE secret); merges to main publish the same tree to staging.hyper.media as they land.
3. Wait for GitHub Actions to complete
The Release - Desktop App workflow builds all platforms and creates the GitHub release (as a prerelease) with the build artifacts attached. Watch it with:
gh run list --workflow release-desktop.yml
gh run watch <run-id>Builds take a while. Do not proceed until the release exists and the workflows are green.
4. Write the release notes
Update the GitHub release body with release notes (gh release edit <tag> --notes-file ...).
The workflow creates the release as a prerelease; publishing the notes is also the moment to promote it: gh release edit <tag> --notes-file <file> --prerelease=false --latest.
Look at the commits since the previous tag (git log <prev-tag>..<tag> --oneline) and at the bodies of the last few releases (gh release view <tag>) to stay consistent in tone and format:
Sections used in past releases: ## ✨ Features and ## 🐛 Bug Fixes (omit an empty section).
End with the changelog link: **Full Changelog**: https://github.com/seed-hypermedia/seed/compare/<prev-tag>...<tag>
Be very short when describing new features. A feature may span 10 commits but is worth only one entry. Group related commits into a single user-facing line.
Do not write notes for fixes to regressions that were introduced and fixed within the same release cycle, the bug was never in a released version, so users never saw it. When in doubt, check whether the buggy commit is reachable from the previous release tag.
Write for users, not developers: describe the visible behavior, not the implementation. Internal-only changes (refactors, CI, tests) are usually not worth an entry.
5. Publish latest.json
Manually run the Generate latest.json (prod) workflow so desktop auto-update picks up the new version:
gh workflow run "Generate latest.json (prod)"Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime