edgeever/docs/release.md

Release Guide

Run a Release

Run from a clean main branch on macOS that matches origin/main:

For any Release that rebuilds desktop assets, first point the release shell at the repository-external Ed25519 key used for the Windows update manifest:

export EDGE_EVER_WINDOWS_UPDATE_SIGNING_KEY=/absolute/path/to/windows-update-ed25519-private.pem

bun run release -- \
  --bump patch \
  --issue-title "Improve the release workflow" \
  --label enhancement \
  --change-en "Run required release checks in parallel." \
  --change-zh "并行执行发布所需检查。" \
  --change-locale "ja:必要なリリースチェックを並列実行します。" \
  --change-commit "abcdef1"

Repeat --change-en, --change-zh, --change-locale ja:, and --change-commit as matching groups. Japanese What's New is required because the App Store listing includes Japanese. One change may cover multiple comma-separated commits:

--change-commit "abcdef1,1234567"

Every commit since the previous formal Release must be covered. Exclude a non-user-facing commit with a concrete reason:

--ignore-commit "89abcde:test-only coverage"

The coverage audit runs before any local or GitHub mutation. Its mapping is stored in the tracking Issue, not in the public Release notes. Public notes contain only user-visible changes, impact, and necessary migration guidance.

Use --dry-run to inspect commit coverage, the native rebuild plan, and notes. After publication, the command does not download, install, or launch the macOS application. Existing macOS, Windows, and Linux installations receive new versions through the in-app automatic updater. Linux Preview releases must pass a real AppImage-to-AppImage transition through the cross-version gate. Pass --install-desktop explicitly only when the previous installation check is actually needed.

EdgeEver-Specific Behavior

• Stable tags and Release titles use vX.Y.Z. Pass --bump explicitly and follow SemVer; do not compress user-visible new capabilities or new platforms into patch for release cadence (see AGENTS.md).
• The root version identifies the product Release. Native marketing versions change only when that native runtime is rebuilt. Android versionCode and iOS build numbers remain independent, monotonically increasing identifiers.
• A formal Release contains macOS arm64 and x64 DMGs, architecture-specific updater ZIPs, an unsigned Windows x64 Preview installer with an independently signed update manifest, a Linux x64 AppImage Preview with updater metadata and a SHA-256 checksum file, and an Android arm64 APK. Unchanged native assets are reused with their original filenames, versions, and checksums.
• Desktop and Android update checks use the version embedded in the applicable Release asset rather than the overall GitHub tag. This prevents a Web-only or API-only Release from prompting an unnecessary native update.
• The script creates the tracking Issue and Draft Release, validates or reuses native assets, prepares and audits the multi-platform GHCR image, publishes, and closes the Issue without installing the desktop application by default; installation remains available as an explicit option. Demo deployment continues independently after its Actions URL is printed.
• A separate workflow sends the same verified Git commit to CNB. CNB builds and audits the public Tencent TCR image inside Tencent Cloud after the formal Release is published. Its duration or failure does not block the GitHub Release or return a published version to Draft.
• After Draft native assets are prepared, publication is blocked unless the Android APK uses the Google Play app-signing certificate. If that gate fails, the Release remains a Draft. Run bun run publish:stores -- --release vX.Y.Z --platform android --android-track production for that Draft, then rerun the original release command to resume. When the audited range includes iOS runtime changes, the same command starts Xcode Cloud and submits App Review after GitHub publication. Once post-publication audits pass, the script closes the tracking Issue and then waits for App Store delivery. An iOS failure leaves the GitHub Release published and that Issue closed; retry with bun run publish:stores -- --release vX.Y.Z --platform ios. See Mobile Store Delivery.
• Web Clipper store submission is a separate official-repository workflow. Run Submit Web Clipper after increasing apps/extension/package.json. It does not run as part of bun run release, and its review does not change a GitHub Release. See Web Clipper store submission.
• Published desktop and Android audits read asset names and download installers through the release API URL. gh release view --json assets and gh release download can stay empty after a draft is published, and treating that empty list as a missing asset set returns the Release to Draft.
• After rebuilt desktop assets are uploaded to the Draft, the local release command signs only latest-windows.json; the private key never enters GitHub Actions. A second desktop workflow run downloads the Windows installer, latest.yml, manifest, signature, and checksum file and independently audits them before publication. See Windows Preview security and updates.

Registry Credentials

The official GitHub repository must define the CNB_TCR_BUILD_PUSH_TOKEN Actions secret with write access only to the CNB source mirror. The private CNB key repository provides TCR_USERNAME and TCR_PASSWORD to the trusted push and tag_push pipelines. For TCR Personal Edition, the username is the Tencent Cloud account ID and the password is the fixed registry password initialized in the TCR console. GHCR is the blocking Release gate. CNB builds TCR from the same Git commit, publishes the same public tags asynchronously, and independently verifies anonymous access and both supported architectures. Independent builds are not required to have the same registry digest.

Failure and Resume

• Validation, Windows signature/audit, Draft asset, or GHCR image failures leave the Release unpublished.
• An asynchronous CNB/TCR build failure leaves the formal Release intact and is repaired or rerun independently.
• Rerunning the same command resumes a matching Draft created by an interrupted run instead of creating another Issue, commit, or Release.
• A failed post-publication native or GHCR audit attempts to return the Release to Draft and leaves the Issue open.
• After those audits pass, the script closes the tracking Issue before waiting for App Store delivery. A later App Store failure leaves that Issue closed.
• If an explicit application installation fails, the script restores the previous app from its macOS Trash backup when possible.