Releasing
How a maintainer cuts a production release of Seed, in order: pick the version number, tag it, wait for the build workflows, write the release notes, and publish latest.json for desktop auto-update.

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.3

When 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

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

People