Skip to content

release-workflow.md

Latest commit

 

History

History
234 lines (162 loc) · 5.83 KB

release-workflow.md

File metadata and controls

234 lines (162 loc) · 5.83 KB

OpenHive Release Workflow

This guide describes how to maintain a shipped OpenHive release while main continues moving toward the next version.

The goal is simple:

  • keep released versions stable
  • keep main free to evolve
  • move bug fixes between those lines in a controlled way

Branch roles

Use these branch types consistently:

  • main — active development for the next minor or major version
  • release/0.9-preview — maintenance branch for all shipped 0.9.x preview patches
  • hotfix/0.9.1-preview-<short-name> — short-lived bug-fix branch cut from release/0.9-preview

For OpenHive, main is expected to carry larger runtime, sandbox, memory, and platform changes that are not safe to push into a shipped patch release.

Core rule

Treat the released line and the active development line separately.

  • Fix released-user bugs on the release branch first
  • Then forward-port the fix to main
  • Do not merge main back into release/0.9-preview

This matters especially in OpenHive because main can contain unfinished architecture work that should not leak into a patch release.

Recommended flow after shipping 0.9.0-preview

1. Tag the release

git checkout main
git pull --ff-only
git tag 0.9.0-preview
git push origin main
git push origin 0.9.0-preview

2. Create the maintenance branch

git checkout -b release/0.9-preview
git push origin release/0.9-preview

After this point:

  • main continues toward 1.0+
  • release/0.9-preview receives only patch-safe fixes

Patch release workflow

When a shipped 0.9.x preview bug is reported:

1. Start from the maintenance branch

git checkout release/0.9-preview
git pull --ff-only
git checkout -b hotfix/0.9.1-preview-fix-<short-name>

2. Make the smallest safe fix

A patch release should prefer:

  • regression tests
  • bug fixes
  • doc corrections
  • tiny compatibility fixes

Avoid bundling:

  • refactors
  • schema churn
  • new features
  • broad runtime or policy changes

3. Merge back into the maintenance branch

git checkout release/0.9-preview
git merge --no-ff hotfix/0.9.1-preview-fix-<short-name>
git push origin release/0.9-preview

4. Tag the patch release

git tag 0.9.1-preview
git push origin 0.9.1-preview

Forward-port to main

After the release-branch fix is merged, copy it into main.

Prefer cherry-pick over merging the whole maintenance branch:

git checkout main
git pull --ff-only
git cherry-pick -x <fix-commit-sha>
git push origin main

Why cherry-pick -x:

  • it moves only the bug fix
  • it avoids pulling release-only decisions into main
  • it leaves a trace back to the original commit

The -x flag records the source commit in the message so later audits are easy.

Backporting from main

Sometimes a bug is discovered and fixed on main first.

Only backport that fix to release/0.9-preview if all of the following are true:

  • the bug affects shipped 0.9.x preview users
  • the fix does not depend on unreleased architecture
  • the fix can land without bringing in risky behavior changes

If those conditions hold, use:

git checkout release/0.9-preview
git pull --ff-only
git cherry-pick -x <main-fix-commit-sha>

If the main fix depends on broader unreleased work, do not force it into the release branch. Instead, implement a smaller release-safe fix directly on release/0.9-preview.

Decision rule for every bug

Ask two questions:

  1. Does this affect the shipped release?
  2. Can it be fixed safely on the old code path?

Use this matrix:

  • Yes / Yes — fix release/0.9-preview first, then forward-port to main
  • No / n/a — fix only main
  • Yes / No — create a smaller release-safe fix on release/0.9-preview, keep the broader solution on main

What is allowed on release/0.9-preview

Allowed:

  • bug fixes
  • regression tests
  • documentation corrections
  • tiny build or packaging fixes

Not allowed unless there is a release-blocking reason:

  • new features
  • API contract changes
  • broad refactors
  • sandbox/runtime architecture work
  • container-orchestration or multi-IM expansion work

For OpenHive's current preview line, this means issues in the active runtime and sandbox tracks stay on main unless they directly block a 0.9.x preview patch.

PR and issue hygiene

For every patch fix:

  • note whether it targets the 0.9.x preview line, main, or both
  • link the bug report or issue
  • state whether the change still needs a forward-port or backport
  • include the regression test when practical

Useful conventions:

  • PR title: hotfix: fix preview dashboard login redirect
  • Branch: hotfix/0.9.1-preview-fix-login-redirect
  • Follow-up PR: forward-port: login redirect fix from release/0.9-preview

Release checklist for patch versions

Before tagging a 0.9.x preview patch:

  • relevant regression tests pass
  • cd web && npm test passes if the fix touches dashboard code
  • cd web && npm run build passes if the fix touches dashboard code
  • docs are updated if operator behavior changed
  • the same fix has a tracked plan for main

Anti-patterns to avoid

Avoid these:

  • merging main into release/0.9-preview
  • letting hotfix branches accumulate unrelated cleanup
  • delaying the forward-port until the context is forgotten
  • backporting a large main refactor just to get one small fix

Minimal example

# release branch hotfix
git checkout release/0.9-preview
git pull --ff-only
git checkout -b hotfix/0.9.2-preview-fix-build-docs

# edit, test, commit
git commit -m "Fix preview docs and dashboard build workflow"

git checkout release/0.9-preview
git merge --no-ff hotfix/0.9.2-preview-fix-build-docs
git tag 0.9.2-preview
git push origin release/0.9-preview
git push origin 0.9.2-preview

# forward-port to main
git checkout main
git pull --ff-only
git cherry-pick -x <hotfix-commit-sha>
git push origin main