Skip to content

RELEASES.md

Latest commit

 

History

History
127 lines (97 loc) · 4.92 KB

RELEASES.md

File metadata and controls

127 lines (97 loc) · 4.92 KB
Raw

Mac Sync Releases

Mac Sync uses the same two-lane release contract as container-compose. Semantic releases are immutable and Current is a replaceable prerelease built from the newest fully validated main commit.

Published Lanes

Lane Git tag Archive Homebrew formula
Stable <major>.<minor>.<patch> mac-sync-release-arm64.tar.gz mac-sync
Current current mac-sync-current-<commit>-arm64.tar.gz mac-sync-current

Stable releases become GitHub Latest. Current uses a commit-addressed asset so the Homebrew formula remains installable while the mutable release is updated. The formula version is current.<workflow-run>.<commit>.

Both lanes require successful CI and CodeQL runs for the exact commit. CI runs the local make ci contract, including the 85% coverage floor and the Sonar quality gate. Release packaging then checks the checksum, archive paths, executables, CLI smoke tests, app plist version/build values, icon, and build-info.json provenance.

The workflow signs an archive with Developer ID when the repository secrets MAC_SYNC_DEVELOPER_ID_CERTIFICATE_P12 (a base64-encoded .p12) and MAC_SYNC_DEVELOPER_ID_CERTIFICATE_PASSWORD are configured. If either secret is absent, it publishes the archive unsigned and reports that fact in the release notes. The workflow validates the certificate authority when signing is enabled.

Developer ID signing does not notarise an app. Notarisation is not currently part of the release workflow, so no archive is presented as a notarised direct-download application.

To enable signing, export the Developer ID Application certificate and private key from Keychain Access as a password-protected .p12. Store its base64 value as the DEVELOPER_ID_APPLICATION_P12_BASE64 repository secret and its export password as DEVELOPER_ID_APPLICATION_P12_PASSWORD. The workflow imports the certificate into an ephemeral runner Keychain and never writes either value to the repository or release asset. The prior MAC_SYNC_DEVELOPER_ID_... and MAC_SYNC_DEVELOPER_ID_CERTIFICATE_... secret names remain supported for migration.

Current Build

A successful main CI run starts the release workflow automatically. It:

  1. Ignores the run if a newer main commit exists.
  2. Waits for exact-commit CI and CodeQL success.
  3. Builds and validates a commit-addressed archive.
  4. Stages the new assets on the existing Current release without moving its tag.
  5. Updates, pushes, installs, and tests mac-sync-current in the Homebrew tap.
  6. Moves only the reserved current tag and recreates the prerelease with a fresh publication time.
  7. Removes assets from superseded releases while retaining their records and tags.

The staging order keeps the previously published Current formula installable until its replacement has been uploaded.

Stable Release

Prepare a release only from a clean, published main commit:

make ci
git fetch --all --prune --no-tags
git status --short --branch
git tag --no-sign 0.1.0
git push origin refs/tags/0.1.0
gh workflow run prebuilt-binaries.yml --ref main -f ref=0.1.0

Replace 0.1.0 with the intended semantic version. Never move or recreate a published semantic tag. The workflow refuses to overwrite an existing stable release or mismatched assets.

The stable workflow publishes the immutable release, updates the default mac-sync formula, installs and tests it from stephenlclarke/homebrew-tap, and then applies asset retention.

Asset Retention

Only these releases retain downloadable assets:

  • current
  • the GitHub Latest stable release

All other release records and Git tags remain visible for changelog and source history. Their binary and checksum assets are deleted after every successful publication. Source archives generated by GitHub from retained tags remain available.

Verification

After publication, verify the actual published heads and assets:

git fetch --all --prune --no-tags
git ls-remote origin refs/heads/main refs/tags/current refs/tags/0.1.0
gh release view current --json tagName,targetCommitish,isPrerelease,assets,url
gh release view 0.1.0 --json tagName,targetCommitish,isLatest,assets,url
gh run list --workflow prebuilt-binaries.yml --limit 5
brew update
brew info stephenlclarke/tap/mac-sync
brew info stephenlclarke/tap/mac-sync-current

Each retained archive has a matching .sha256 sidecar. The workflow also compares the local archive digest with GitHub's published asset digest.

Rollback

Do not move a semantic tag or rewrite main.

For a bad Current build, fix or revert the source on main; the resulting successful CI run publishes a replacement Current build. Users can return to stable with:

brew uninstall mac-sync-current
brew install mac-sync

For a stable regression, publish a new patch release and update the stable formula through the release workflow. Existing release records remain as the audit trail even after their superseded assets are pruned.