Publish Release

Publish an Econumo release

Releases are cut by the Publish Release workflow (.github/workflows/publish-release.yml), never by pushing tags or images locally. The workflow's branch input selects the source branch (main by default; a release/* branch for hotfixes), and the dispatch itself always uses --ref main so the workflow definition never comes from a stale branch. The workflow does three things in order: creates the annotated git tag at the source branch's head (a release from main also leaves a release/vX.Y.Z branch at the same commit — the base for future hotfixes to that version; a release from a release/* source creates no branch, because that source is itself the release branch), builds and pushes the multi-arch image to ghcr.io/econumo/econumo, and creates the GitHub release with auto-generated notes (changelogithub). Your job is to drive it, verify each artifact, and then replace the auto-generated notes with notes a human would want to read.

Publishing is outward-facing and irreversible in practice (the tag and image are public immediately). Only run the dispatch when the user has explicitly asked for a release, and if they didn't name the version, propose one and get confirmation first.

1. Establish the baseline

git tag --sort=-creatordate | head -5        # last released version
gh release list --limit 3
git fetch origin main --quiet
git log vLAST..origin/main --oneline          # everything the release will contain

Pick the version by semver over that range: any feat: → minor bump; fixes/chores only → patch. Sanity-check that main is what the user intends to release (no surprising or half-landed work in the log) and that the latest run of the Go tests workflow on main is green (gh run list --workflow=go-tests.yml --branch main --limit 1). Surface anything odd before dispatching — after dispatch there is no undo.

For a hotfix of an older version the version is a patch bump of that line (bug in v1.1.1 → v1.1.2), regardless of what has since shipped from main.

2. Prepare the source branch (hotfixes only)

For a normal release there is nothing to prepare — releasing from main auto-creates release/vX.Y.Z at the released commit, so every version cut from main leaves a branch behind as the base for future fixes.

For a hotfix, the workflow creates NO branch (the rule: release branches are only created for releases from main) — the new version's branch is prepared by hand. Copy the fixed version's release branch to the new version's name, then land the fixes on the copy:

git fetch origin --tags --quiet
# the new version's branch, copied from the fixed version's release branch:
git push origin origin/release/vA.B.C:refs/heads/release/vX.Y.Z
# or, if vA.B.C predates release branches, from its tag:
git push origin 'vA.B.C^{}':refs/heads/release/vX.Y.Z

Land the fixes on release/vX.Y.Z — cherry-pick the fix commits from main onto a working branch and PR it with that branch as the base (or push the cherry-picks directly if the user prefers). The old branch release/vA.B.C stays untouched at its released commit, so every release branch keeps pointing at exactly what its version shipped.

Confirm with git log origin/release/vX.Y.Z that the branch holds exactly the intended fixes and nothing else from main. Note the test workflows ignore pushes to release/** — only the PR route runs tests on the fixes, which is why it is the default; after a direct push, run the suites locally before dispatching.

The fix must reach main too, or the next release from main regresses the bug. Release branches are never merged wholesale into main — they exist to pin what shipped; the fix flows back at the commit level. Default direction: the fix lands on main FIRST (normal PR) and is cherry-picked onto the release branch, so there is nothing to port back. Only when the fix has to be authored on the release branch directly (the code on main has diverged or the bug no longer exists there in the same shape) does it need a forward-port: after the release, cherry-pick it onto a working branch and PR it into main. Audit that nothing was left behind:

git log --no-merges --right-only --cherry-pick --oneline main...origin/release/vX.Y.Z

Empty output means every commit on the release branch is patch-equivalent to one on main; anything listed still needs a forward-port (or a deliberate decision that main doesn't need it — say so in the release notes).

3. Dispatch and watch

# Normal release (source defaults to main):
gh workflow run publish-release.yml --ref main -f version=vX.Y.Z -f push_latest=true

# Hotfix (source = the NEW version's hand-prepared release branch):
gh workflow run publish-release.yml --ref main -f version=vX.Y.Z -f branch=release/vX.Y.Z

• Always dispatch with --ref main; the branch input (default main) is what selects the code being released.
• push_latest=true is the norm when releasing the newest version. The workflow enforces it: latest only moves when the source branch is main or release/* AND the version is higher than every existing tag. For a hotfix of an older line, leave it off — the guard would reject it anyway. Leave it off for pre-releases/betas too.
• The workflow fails fast if the tag already exists.
• Grab the run id (gh run list --workflow=publish-release.yml --limit 1) and watch it in the background: gh run watch <run-id> --exit-status --interval 30 via a background Bash call. The image build is the long step (several minutes) — use that time for step 4.