Skip to content

release-flow.md

Latest commit

 

History

History
223 lines (158 loc) · 8.24 KB

release-flow.md

File metadata and controls

223 lines (158 loc) · 8.24 KB
Raw

Release Flow

This document defines the maintainer release flow for DeepChat without rewriting existing dev / main history.

Goals

  • Keep dev as the only long-lived integration branch.
  • Keep main as a stable mirror of reviewed release commits.
  • Keep releases tag-driven through .github/workflows/release.yml.
  • Avoid creating new merge commits on main.

Branch Roles

  • dev: active development and integration branch.
  • main: stable mirror of released source snapshots.
  • release/<version>: short-lived review branch cut from an existing commit on dev.

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

Standard Release Sequence

  1. Prepare release metadata on dev.

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

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

    git switch dev
git pull --ff-only origin dev
git switch -c release/v1.0.0-beta.4
git push -u origin release/v1.0.0-beta.4

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

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

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

    git switch dev
git pull --ff-only origin dev
# land the release fix on dev
git branch -f release/v1.0.0-beta.4 origin/dev
git switch release/v1.0.0-beta.4
git push --force-with-lease origin release/v1.0.0-beta.4

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

  5. After the PR is approved, fast-forward main locally on macOS or Linux.

    pnpm run release:ff -- release/v1.0.0-beta.4 --tag v1.0.0-beta.4

    The helper script validates:

    • the working tree is clean
    • the target release commit already exists on origin/dev
    • origin/main is an ancestor of the target commit
    • main can be updated with git merge --ff-only
    • the requested tag is free locally and on origin

    The --tag option validates tag availability and prints the tag command. Create and push the tag in the next step.

    Windows maintainers should skip this helper and use the manual release sequence below.

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

    git tag v1.0.0-beta.4 release/v1.0.0-beta.4
git push origin v1.0.0-beta.4

  7. Wait for the tag-triggered Release workflow and review its draft.

    • Preflight must resolve the existing tag to the expected commit, confirm that commit is reachable from origin/main, match package.json, and find a non-empty matching CHANGELOG section before any native package starts.
    • All six native package jobs must pass. macOS x64 and ARM64 must be signed, notarized, stapled, and verified; Windows remains unsigned.
    • The workflow writes the draft only after fail-closed assembly and local revalidation, then verifies the uploaded assets through the GitHub API. Treat the run as successful only after that remote size and digest verification passes. Do not add ad hoc assets to the draft.
    • The draft must contain exactly nineteen assets: fourteen target files, four updater metadata files, and release-index.json.
    • If a release run must be retried after a native job has completed, rerun all jobs. Package manifests bind GITHUB_RUN_ATTEMPT, so mixing artifacts from different attempts intentionally fails assembly.

    Publish the verified draft manually after reviewing its notes, target list, and release-index.json.

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

    git push origin --delete release/v1.0.0-beta.4
git branch -d release/v1.0.0-beta.4

Manual Release Sequence

Use this sequence when the automatic helper is unavailable, especially on Windows. It updates origin/main directly from the reviewed release commit and does not depend on the state of your local main.

  1. Fetch the latest release refs.

    git fetch origin main dev --prune

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

    git rev-parse origin/release/v1.0.0-beta.4^{commit}
# or
git rev-parse release/v1.0.0-beta.4^{commit}
# or
git rev-parse <target-ref>^{commit}

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

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

  4. Confirm origin/main can be fast-forwarded to the reviewed release commit.

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

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

    git rev-parse --verify --quiet refs/tags/v1.0.0-beta.4
git ls-remote --exit-code --tags origin refs/tags/v1.0.0-beta.4

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

  6. Fast-forward origin/main directly to the reviewed release commit.

    git push origin <TARGET_SHA>:refs/heads/main

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

    git tag v1.0.0-beta.4 <TARGET_SHA>
git push origin refs/tags/v1.0.0-beta.4

  8. Wait for the Release workflow, review the exact nineteen-asset draft using the checks in the standard sequence, and publish it manually.

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

    git push origin --delete release/v1.0.0-beta.4
git branch -d release/v1.0.0-beta.4

Repository Settings

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

  • Enable Require linear history on main.
  • Keep PR checks required for PRs targeting main and dev.
  • Allow maintainers to push main only through the documented ff-only procedure.
  • Treat the PR merge button for main as disabled by policy, even if the repository UI still shows it.

CI Guardrails

  • PRs targeting main must come from release/<version> branches.
  • The head commit of a PR targeting main must already be contained in origin/dev.
  • Release tags must point to commits that are already reachable from origin/main.

Build, Release, and package regression call one reusable workflow per operating system. The fixed native runner and unpacked-directory mapping live in those called workflows, not in each caller. Secrets are passed explicitly; package jobs have only contents: read, and only the final draft publication job has contents: write.

Release assembly accepts exactly one distribution manifest for each of Windows, Linux, and macOS on x64 and ARM64. It recomputes file digests, rejects incomplete checks or unknown files, and generates:

  • latest.yml for Windows x64 and ARM64 NSIS payloads;
  • latest-mac.yml for macOS x64 and ARM64 ZIP payloads, never DMGs;
  • separate latest-linux.yml and latest-linux-arm64.yml AppImage metadata;
  • release-index.json with six-target evidence and SHA-256 for the other eighteen public files.

Windows ARM64 uses the build:win:arm64 script, installs only runtime payloads available for win32/arm64, and packages only plugins whose manifest declares that target. Artifact names and update metadata retain architecture so an ARM64 build cannot replace or be served as an x64 package. The equivalent platform/architecture contract for bundled plugins is documented in plugin packaging.

These rules are enforced in the repository workflows so the documented flow and the automation stay aligned.

History Hygiene

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

git log --oneline --decorate --first-parent dev -n 30
git log --oneline --decorate --first-parent main -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 dev