Skip to content

release-process.md

Latest commit

 

History

History
95 lines (81 loc) · 4.38 KB

release-process.md

File metadata and controls

95 lines (81 loc) · 4.38 KB
Raw

Release process

Bridge supports development and unsigned bundle smoke validation on Windows and macOS. A smoke bundle is not a production release.

Supported build baseline

  • Source release line: 0.2.x under Apache-2.0
  • Node.js: supported 22 or 24 releases; CI uses .node-version
  • pnpm: the exact packageManager version in package.json
  • Rust: the exact channel and components in rust-toolchain.toml
  • Hosts: current GitHub-hosted Windows and macOS runners plus native maintainer validation for vendor integrations

Candidate gates

Before cutting a candidate, regenerate and verify the Rust third-party notice with the pinned generator:

cargo install --locked cargo-about --version 0.9.1 --features cli
corepack pnpm run license:generate:rust
corepack pnpm run license:all

  1. Update package.json, src-tauri/Cargo.toml, and src-tauri/tauri.conf.json to the same version.

  2. Move completed changelog entries into that version and retain the MIT notice for historical v0.1.0.

  3. Run corepack pnpm install --frozen-lockfile and corepack pnpm run license:all.

  4. Run frontend build, Rust format/check/test/Clippy, and native Tauri bundle builds on Windows and macOS.

  5. Confirm the bundle-smoke jobs pass their automated MSI, NSIS, staged macOS app, and mounted DMG inspections for LICENSE, NOTICE, THIRD_PARTY_LICENSES.txt, and THIRD_PARTY_LICENSES_RUST.txt; manually inspect signed candidates again before publication.

  6. Exercise Tally, DSC, documents, sync, and persistence using synthetic data; attach redacted evidence to the release PR. Keep repository-synthetic parser qualification receipts separate from the live Tally compatibility matrix: they cannot establish a product release, Education/licensed mode, HTTP/runtime behavior, or a performance budget. Do not broaden a Tally support claim without current exact-profile live evidence; state missing matrix evidence in the release notes. Run the executable Tally claim gate:

    cd src-tauri
cargo run --locked -p bridge-tally-compatibility -- gate \
  ../docs/tally/compatibility/compatibility-matrix.json \
  ../docs/tally/compatibility/compatibility-surface.json \
  ../docs/tally/compatibility/trusted-evidence-keys.json \
  ../docs/tally/compatibility/evidence ..

    Any positive cell without an exact fresh signed receipt is a release blocker. Unknown cells remain visible limitations; they are not failures unless release notes or product copy claim that scope. Live Education collection, when legitimately available, must follow the read-only runbook. Never upload .bridge-live/ automatically or substitute the parser-only CI receipt for reviewed live evidence.

  7. Confirm the release commit and tag contain no PII, machine paths, secrets, or unsigned third-party assets.

  8. Confirm the Dependency security workflow passes and GitHub reports no open Dependabot or secret-scanning alerts.

Signing and publication

  • Windows production installers require an organization-controlled code-signing certificate and timestamp service.
  • macOS production bundles require an organization-controlled Developer ID, hardened runtime, notarization, and stapling.
  • Signing credentials belong in protected release environments with required reviewers; never place them in repository variables, logs, or artifacts.
  • Publish SHA-256 checksums and provenance/attestation evidence with every downloadable artifact.
  • Do not create or move a v* tag until signed artifacts from both supported platforms pass the candidate gates. Release tags must be immutable.

The repository intentionally does not auto-publish unsigned tag artifacts. CI bundle jobs produce short-lived smoke evidence only until signing and notarization ownership is configured.

Rollback

  1. Mark the affected GitHub release as withdrawn and remove unsafe downloadable artifacts without moving or reusing its tag.
  2. Publish a security advisory when coordinated disclosure is required.
  3. Revert or rectify the source change through a pull request with migration compatibility notes.
  4. Cut a new patch version; never replace an already published artifact under the same version or checksum.
  5. Preserve release notes explaining impact, upgrade/rollback steps, and the last known-good version without including customer data.