Skip to content

release-lifecycle.md

Latest commit

 

History

History
123 lines (97 loc) · 4.08 KB

release-lifecycle.md

File metadata and controls

123 lines (97 loc) · 4.08 KB
Raw

Release lifecycle — 1Helm

Process contract from intent to verified deploy. Commands: release-checklist.md.

  intent / issue
       │
       v
  branch from origin/main
       │
       v
  implement + tests + VISION (if decision) + CHANGELOG Unreleased
       │
       v
  typecheck · build · npm test · PR
       │
       v
  squash/merge · delete branch · CI green on main
       │
       v
  version bump on the release branch
       │
       v
  full numbered notes · tag · signed DMG + updater ZIP + Linux host artifact
                         + signed universal APK + App Store mobile archive
       │
       v
  verify (local health + clean install + public artifact)
       │
       v
  done (evidence)

1. Plan

  • Prefer issues for user-visible work.
  • One PR ≈ one concern. Do not mix unrelated refactors into a hotfix.
  • If the change is product direction, update docs/VISION.md in the same PR.

2. Branch and implement

git fetch origin
git switch main && git pull --ff-only origin main
git switch -c feat/short-slug
  • Work in the tree that matches the process under test (verify port → cwd).
  • Preserve dirty unrelated worktrees; use a clean worktree for release/governance if needed.

3. Verify before review

PUPPETEER_SKIP_DOWNLOAD=1 npm ci   # or npm install
npm run typecheck
npm run build
npm test
git diff --check

Feature branches that introduce test/native-world.mjs (or similar) must run those suites before merge.

4. Pull request

Use the PR template: summary, type, changelog bullets, numbered acceptance ledger, and verification checklist. For a multi-item request, preserve its numbering and record one concrete outcome per item. The ledger is the source for the GitHub Release; a commit title or generated summary is not a substitute.

Draft PRs are allowed for long slices; mark ready only when the quality bar is met.

5. Merge

  • Prefer squash into main.
  • Delete the head branch.
  • Confirm Actions on main.

6. Version and changelog for a named cut

  1. Move Unreleased notes into ## [x.y.z] - YYYY-MM-DD.
  2. npm version patch|minor|major --no-git-tag-version (or edit package.json).
  3. Commit the versioned source on the release branch before merge.
  4. After merge, tag the exact verified main commit and push the tag.
  5. Author release notes from the PR acceptance ledger using release-notes-template.md. Every accepted user-visible item must appear once, with the same numbering as the request when available. Include additional fixes, artifacts/digests, and verification evidence in their own sections.
  6. Publish the verified DMG, native updater ZIP, Linux host artifact, any directly distributed signed Android APK, and those complete release notes through one GitHub Release. Submit an iOS build through App Store Connect rather than publishing an installable IPA as a generic download. Do not use GitHub's generated notes as the sole or primary body.

7. Deploy

Local service

  • Build in the target tree.
  • Preserve the configured CTRL_DATA_DIR, restart the intended exact service, and verify loopback health after startup.

Public sandbox

# operator-specific deployment commands live outside the public repository

Confirm /api/setup/status on the intended sandbox without reusing production workspace state.

8. What “done” means

Claim Evidence
Code landed On origin/main, CI green
Behavior fixed Tests + manual/API check
Install path still works Clean CTRL_DATA_DIR boot through the wizard plus platform acceptance
Named release Version, changelog, full numbered notes, exact tag, verified public artifact, and clean installation
Native host update Published updater ZIP feed, installed-old-to-new Mac acceptance, and preserved Application Support
Linux host update Digest-qualified artifact, real systemd old-to-new update, health check, and preserved /var/lib/1helm

If deploy verification was skipped, say so. Do not call a ship “done.”