Skip to content

release-flow.md

Latest commit

 

History

History
176 lines (120 loc) · 5.33 KB

release-flow.md

File metadata and controls

176 lines (120 loc) · 5.33 KB
Raw

Release Flow

This document defines the maintainer release flow for Argos.

Goals

  • Keep master as the only long-lived integration branch.
  • Keep releases tag-driven through .github/workflows/release.yml.
  • Avoid creating unnecessary merge commits on master.

Remote-machine release notes

Every release that changes the daemon or desktop connection surface should include two clearly separated asset groups:

  • Argos Desktop (recommended): the normal platform installer for local use.
  • Argos Server (advanced/headless): the matching argos-daemon-<os>-<arch> binary for a remote host, including its SHA-256 checksum.

Release notes should link to the remote-machine guide and state the supported pairing/protocol version. Do not tell local users to download the standalone daemon.

Branch Roles

  • master: active development and integration branch.
  • release/<version>: short-lived review branch cut from an existing commit on master.

release/<version> must not carry release-only commits. If a release fix is required, land it on master first and then move the release branch forward to the updated master commit.

Standard Release Sequence

  1. Prepare release metadata on master.

    • Update the version, CHANGELOG.md, and any release notes on master.
    • Run the required local checks before cutting a release branch.

  2. Cut the review branch from the release-ready commit on master.

    git switch master
git pull --ff-only origin master
git switch -c release/v0.1.0
git push -u origin release/v0.1.0

  3. Open a PR from release/<version> to master.

    • The PR exists for review and CI only.
    • Do not click "Update branch" on the PR, because it creates new merge commits.

  4. If review finds a release issue, fix it on master first.

    git switch master
git pull --ff-only origin master
# land the release fix on master
git branch -f release/v0.1.0 origin/master
git switch release/v0.1.0
git push --force-with-lease origin release/v0.1.0

    Use --force-with-lease only because the release branch is a disposable review branch that must stay identical to a commit already on master.

  5. After the PR is approved, merge to master.

    git switch master
git merge --ff-only release/v0.1.0
git push origin master

  6. Create and push the release tag on the same commit.

    git tag v0.1.0 release/v0.1.0
git push origin v0.1.0

  7. Delete the temporary release branch after the release is published.

    git push origin --delete release/v0.1.0
git branch -d release/v0.1.0

Manual Release Sequence

Use this sequence when the automatic helper is unavailable, especially on Windows. It merges the reviewed release commit to master directly.

  1. Fetch the latest release refs.

    git fetch origin master --prune

  2. Resolve the reviewed release commit and record it as TARGET_SHA.

    git rev-parse origin/release/v0.1.0^{commit}
# or
git rev-parse release/v0.1.0^{commit}
# or
git rev-parse <target-ref>^{commit}

  3. Confirm the release commit already exists on origin/master.

    git merge-base --is-ancestor <TARGET_SHA> origin/master

  4. The release branch merge target is master.

  5. Confirm the release tag does not already exist locally or on origin.

    git rev-parse --verify --quiet refs/tags/v0.1.0
git ls-remote --exit-code --tags origin refs/tags/v0.1.0

    Both commands should report that the tag is missing before you continue.

  6. Merge to master locally.

    git switch master
git merge --ff-only <TARGET_SHA>
git push origin master

  7. Create and push the release tag on the same commit.

    git tag v0.1.0 <TARGET_SHA>
git push origin refs/tags/v0.1.0

  8. Delete the temporary release branch after the release is published.

    git push origin --delete release/v0.1.0
git branch -d release/v0.1.0

Repository Settings

These settings are not stored in the repository and must be configured manually on GitHub:

  • Enable Require linear history on master.
  • Keep PR checks required for PRs targeting master.

CI Guardrails

  • Routine feature, bugfix, docs, and test PRs target master and run the PR checks in .github/workflows/prcheck.yml (lint, format, typecheck/build of affected packages, daemon unit tests).
  • Release review PRs (release/<version> → master) exist for review and CI only; do not click "Update branch" on them.
  • Release tags must point to commits that are already reachable from origin/master. This is enforced by the validate-main-ancestor job in .github/workflows/release.yml.

These rules keep the documented flow and the automation aligned.

History Hygiene

Use first-parent history for day-to-day inspection:

git log --oneline --decorate --first-parent master -n 30

Avoid using git log --all --decorate --graph as the default project view because old release merges and stale branch refs make it noisier than the actual mainline history.

Clean up short-lived branches after they are merged:

git fetch --prune origin
git branch --merged master