feat(HAI-109): add binary release infrastructure and dual-channel release workflow
- Add binary build verification step to CI workflow - Add binary release job to release.yml for platform-specific builds - Restore test-release workflow for pre-release validation - Update CI workflow tests to cover binary release infrastructure - Update RELEASING.md with dual-channel (npm + binary) release process
This commit is contained in:
47
RELEASING.md
47
RELEASING.md
@@ -1,6 +1,9 @@
|
||||
# Releasing
|
||||
|
||||
This project uses [changesets](https://github.com/changesets/changesets) for automated versioning and release management.
|
||||
This project uses [changesets](https://github.com/changesets/changesets) for automated versioning and release management. Releases are distributed through two channels:
|
||||
|
||||
1. **npm packages** — published automatically via `version.yml` using changesets
|
||||
2. **GitHub Release with platform binaries** — built and uploaded via `release.yml` when a version tag is pushed
|
||||
|
||||
## How it works
|
||||
|
||||
@@ -21,7 +24,7 @@ A markdown file will be created in the `.changeset/` directory. Commit this file
|
||||
|
||||
### 2. Version PR is created automatically
|
||||
|
||||
When changesets are merged to `main`, a GitHub Actions workflow automatically opens (or updates) a **"Version Packages"** pull request. This PR:
|
||||
When changesets are merged to `main`, the `version.yml` workflow automatically opens (or updates) a **"Version Packages"** pull request. This PR:
|
||||
|
||||
- Consumes all pending changeset files
|
||||
- Bumps package versions according to the changeset declarations
|
||||
@@ -31,10 +34,38 @@ When changesets are merged to `main`, a GitHub Actions workflow automatically op
|
||||
|
||||
When you merge the Version Packages PR:
|
||||
|
||||
- The workflow detects that all changesets have been consumed
|
||||
- The `version.yml` workflow detects that all changesets have been consumed
|
||||
- It builds all packages and publishes them to **npm** with provenance attestation
|
||||
- It creates a git tag `v{version}` based on the `hai` CLI package version
|
||||
- The tag push triggers the existing release workflow (`.github/workflows/release.yml`)
|
||||
- The release workflow builds binaries and creates a GitHub Release
|
||||
- The tag push triggers `release.yml`, which:
|
||||
- Builds platform-specific binaries for Linux x64, macOS x64, macOS arm64, and Windows x64
|
||||
- Signs macOS binaries (codesign + notarization) and Windows binaries (Authenticode)
|
||||
- Generates SHA256 checksums for all binaries
|
||||
- Creates a **GitHub Release** with all binaries and checksums attached
|
||||
|
||||
## Release channels
|
||||
|
||||
| Channel | Workflow | Trigger | Output |
|
||||
|---------|----------|---------|--------|
|
||||
| npm | `version.yml` | Push to `main` | npm packages with provenance |
|
||||
| GitHub Release | `release.yml` | Version tag (`v*`) | Signed platform binaries + checksums |
|
||||
|
||||
## Platform binaries
|
||||
|
||||
| Platform | Binary name | Signed |
|
||||
|----------|------------|--------|
|
||||
| Linux x64 | `hai-linux-x64` | — |
|
||||
| macOS arm64 | `hai-darwin-arm64` | ✓ (codesign + notarization) |
|
||||
| macOS x64 | `hai-darwin-x64` | ✓ (codesign + notarization) |
|
||||
| Windows x64 | `hai-windows-x64.exe` | ✓ (Authenticode) |
|
||||
|
||||
## Testing binary builds
|
||||
|
||||
Use the **Test Release** workflow (`test-release.yml`) to manually test binary builds without creating a real release:
|
||||
|
||||
1. Go to **Actions** → **Test Release** → **Run workflow**
|
||||
2. The workflow builds all 4 platform binaries, runs smoke tests, and uploads artifacts
|
||||
3. Download the `all-binaries` artifact to inspect the output
|
||||
|
||||
## Manual release (fallback)
|
||||
|
||||
@@ -45,7 +76,7 @@ git tag v0.2.0
|
||||
git push origin v0.2.0
|
||||
```
|
||||
|
||||
This will trigger the release workflow. Note: the workflow validates that the tag version matches `packages/cli/package.json`, so make sure they're in sync.
|
||||
This will trigger `release.yml` to build binaries and create a GitHub Release. Note: npm publishing is handled separately by `version.yml` and won't be triggered by a manual tag push.
|
||||
|
||||
## Available scripts
|
||||
|
||||
@@ -54,9 +85,13 @@ This will trigger the release workflow. Note: the workflow validates that the ta
|
||||
| `pnpm changeset` | Add a new changeset |
|
||||
| `pnpm changeset status` | Check pending changesets |
|
||||
| `pnpm release:version` | Apply changesets and bump versions (used by CI) |
|
||||
| `pnpm --filter hai build:exe` | Build binary for current platform |
|
||||
| `pnpm --filter hai build:exe -- --target <target>` | Cross-compile for a specific platform |
|
||||
| `pnpm --filter hai build:exe:all` | Build binaries for all platforms |
|
||||
|
||||
## Tips
|
||||
|
||||
- Every user-facing change should have a changeset — CI will remind you if one is missing
|
||||
- You can add multiple changesets per PR if you're making changes to multiple packages
|
||||
- Changeset files are automatically deleted when versions are bumped
|
||||
- CI verifies binary compilation on every push/PR to catch build regressions early
|
||||
|
||||
Reference in New Issue
Block a user