This page is the list of steps a maintainer follows to make a production release of Seed. A release ships three things: the desktop app, the Docker images, and the production copy of these docs. Each step depends on the one before it, so do them in order. The .agents/skills/run-release skill in the repository takes a coding agent through the same steps.
1. Determine the release number
A version has the form YYYY.M.N: the year, the month with no leading zero, and a number that counts the releases in that month. The third release of July 2026 is 2026.7.3.
Find the last release with git tag --sort=-creatordate | head -5. If the latest tag is from this month, add one to its last number. If not, start at .1 for the new month.
2. Tag the release
Tag the commit you want to release, normally the newest commit on main, and push the tag:
git tag 2026.7.3
git push origin 2026.7.3When you push a *.*.* tag, two release workflows start: Release - Desktop App and Release - Docker Images. The last job of the Docker workflow publishes the released hypermedia/ folder to the docs on hyper.media. It does this with the Repo HM sync (hypermedia) workflow and the target production. A release is the only way the docs reach production. A merge to main publishes to staging.hyper.media. See Editing these docs.
3. Wait for GitHub Actions to complete
The Release - Desktop App workflow builds the app for every platform. Then it creates the GitHub release, as a prerelease, with the built files attached. Watch it with:
gh run list --workflow release-desktop.yml
gh run watch <run-id>The builds take some time. Do not go on until the release exists and the workflows have passed.
4. Write the release notes
Put the release notes in the body of the GitHub release (gh release edit <tag> --notes-file ...).
The workflow creates the release as a prerelease. When you publish the notes, also make it the latest release: gh release edit <tag> --notes-file <file> --prerelease=false --latest.
Read the commits since the last tag (git log <prev-tag>..<tag> --oneline) and the notes of the last few releases (gh release view <tag>), so that the tone and the format stay the same:
Past releases use these sections: ## ✨ Features and ## 🐛 Bug Fixes. Leave out an empty section.
End with the changelog link: **Full Changelog**: https://github.com/seed-hypermedia/seed/compare/<prev-tag>...<tag>
Describe a new feature in very few words. A feature may take 10 commits, but it gets one entry. Put related commits into one line that a user understands.
Do not write a note for the fix of a bug that was added and fixed between two releases. The bug was never in a released version, so users never saw it. If you are not sure, check whether the commit with the bug can be reached from the last release tag.
Write for users, not for developers. Describe what a user sees, not how the code works. A change that only developers see (a refactor, CI, tests) usually gets no entry.
5. Publish latest.json
Start the Generate latest.json (prod) workflow by hand. The desktop app reads latest.json to find a new version, so this step makes the app update itself:
gh workflow run "Generate latest.json (prod)"See also
Package publishing, for the npm packages, which do not wait for a release.
Editing these docs, for what the release publishes to hyper.media.
The desktop app, which reads latest.json to update itself.
Working on Seed, the list of contributor guides.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime