From 702b231c4abced391f0e4c951bd31c449f3925c0 Mon Sep 17 00:00:00 2001 From: Jason Farrar Date: Mon, 6 Jul 2026 15:15:05 +0100 Subject: [PATCH] fix: create draft releases and defer cleanup until manual promotion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add 'draft: true' to all 4 softprops/action-gh-release upload steps (Linux, Linux ARM64, Windows, macOS) - Draft releases prevent premature publication while allowing time for verification - Modified cleanup job to skip draft releases until manually promoted from draft → published - Cleanup job now checks isDraft flag before stripping old release assets - Draft releases won't be cleaned up until promoted by maintainer This addresses issue #81: Release workflow should create draft releases. Releases must be manually promoted after verification and platform-specific checks (e.g., Windows MSI submission to Microsoft WDSI portal, macOS notarisation). --- .github/workflows/release.yml | 14 +++ RELEASE.md | 189 ++++++++++++++++++++++++++++++++++ 2 files changed, 203 insertions(+) create mode 100644 RELEASE.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 03a1ea2..3aca553 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -175,6 +175,7 @@ jobs: - name: Upload .deb and .rpm to release uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0 with: + draft: true files: | dist/*.deb dist/*.rpm @@ -289,6 +290,7 @@ jobs: - name: Upload ARM64 .deb and .rpm to release uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0 with: + draft: true files: | dist/*.deb dist/*.rpm @@ -436,6 +438,7 @@ jobs: - name: Upload .msi to release uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0 with: + draft: true files: dist/*.msi env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -782,6 +785,7 @@ jobs: - name: Upload .dmg to release uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0 with: + draft: true files: dist/*.dmg env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -843,6 +847,16 @@ jobs: continue fi + # ── Skip draft releases — they will be cleaned up after promotion ── + IS_DRAFT=$(gh release view "$TAG" \ + --repo "$REPO" \ + --json isDraft \ + --jq '.isDraft' 2>/dev/null || echo "false") + if [ "$IS_DRAFT" = "true" ]; then + echo "[${INDEX}] SKIP ${TAG} (draft release — waiting for manual promotion)" + continue + fi + echo "[${INDEX}] STRIP ${TAG}" # ── Delete every existing asset on this release ────────────────── diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..deedbe1 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,189 @@ +# Release Workflow & Promotion Checklist + +## Overview + +The `openstan` release process creates **draft releases** automatically via GitHub Actions when a version tag is pushed. Releases must be **manually promoted** from draft to published after verification and platform-specific checks. + +This approach prevents premature publication while allowing time to: +- Verify all platform binaries are correct +- Submit Windows MSI to Microsoft WDSI portal for SmartScreen clearance +- Resolve any CI configuration issues without polluting the release history + +--- + +## Quick Start: Create a Release + +### 1. Push a version tag + +```bash +git tag v1.2.3 +git push origin v1.2.3 +``` + +The tag must match the pattern `v*` (e.g. `v0.1.5`, `v1.0.0-rc1`). The workflow is triggered automatically. + +### 2. Wait for builds to complete + +All four platform jobs must complete successfully: +- Linux (.deb + .rpm) +- Linux ARM64 (_arm64.deb + .aarch64.rpm) +- Windows (.msi) +- macOS (.dmg) + +Monitor progress at: `https://github.com/boscorat/openstan/actions` + +Build time typically: **30–45 minutes** (varies by platform) + +--- + +## Release Promotion Checklist + +Once all builds complete, the **draft release** will be created at: +`https://github.com/boscorat/openstan/releases` + +Follow this checklist before promoting from draft to published: + +### Pre-Publication Verification + +- [ ] **All platform binaries attached** + - [ ] `openstan-X.Y.Z-Linux-Ubuntu-x86_64.deb` (64-bit) + - [ ] `openstan-X.Y.Z-Linux-Ubuntu-arm64.deb` (ARM64) + - [ ] `openstan-X.Y.Z-Linux-Fedora-x86_64.rpm` (64-bit) + - [ ] `openstan-X.Y.Z-Linux-Fedora-arm64.rpm` (ARM64) + - [ ] `openstan-X.Y.Z-Windows.msi` (Windows) + - [ ] `openstan-X.Y.Z-macOS.dmg` (macOS) + +- [ ] **Release notes are present and accurate** + - Describe key features, bug fixes, or changes + - Include any known issues or breaking changes + - Link to GitHub milestone/pull requests if applicable + +- [ ] **macOS .dmg is notarised** + - The workflow automatically handles code signing and Apple notarisation + - No manual action needed — if the macOS build succeeded, it's notarised + - Verify: Try opening the .dmg on a Mac; no Gatekeeper warnings should appear + +- [ ] **Windows .msi submission (WDSI portal)** + - [ ] Go to https://www.microsoft.com/en-us/wdsi/filesubmission + - [ ] Sign in with your Microsoft account + - [ ] Select "Software" → "Incorrect detection" → "Clean software" + - [ ] Upload the .msi file + - [ ] **Allow 24–48 hours for Microsoft to review** + - [ ] Once approved, SmartScreen warnings will be cleared + + *Note: This step is critical if the Windows installer is to be widely distributed. SmartScreen reputation builds over time with downloads; without WDSI submission, Windows may initially warn users about the unsigned binary.* + +### No Breaking Changes? + +- [ ] Review changelog for any API or UI breaking changes + - If breaking changes are present, increment the **major** version + - Otherwise, follow semantic versioning (minor for features, patch for fixes) +- [ ] All deprecation warnings added in previous releases are documented + +--- + +## Manual Promotion: Draft → Published + +Once the checklist is complete and Microsoft has cleared the .msi (if applicable): + +### Option A: Using GitHub CLI + +```bash +gh release edit v1.2.3 --draft=false +``` + +### Option B: Using GitHub Web UI + +1. Go to `https://github.com/boscorat/openstan/releases` +2. Click on the draft release +3. Click **"Edit"** (pencil icon, top-right) +4. Uncheck **"This is a pre-release"** (if applicable) +5. Uncheck **"Set as a draft"** checkbox +6. Click **"Publish release"** + +### Result + +- Release is now **published** and visible to all users +- Appears on the **Releases** page as a normal (not draft) release +- May be tagged "Latest" if appropriate +- Announcement can be made on social media, blog, etc. + +--- + +## Post-Publication + +After publishing: + +- [ ] The **cleanup job** automatically runs after all builds + - Strips binaries from releases older than the **5 most recent** + - Leaves a `NOTICE.txt` pointing users to the latest version + - Keeps draft releases intact until they're manually promoted + +- [ ] Announce the release (if desired) + - GitHub Discussions + - Project website + - Social media + - Email newsletter + +--- + +## Troubleshooting + +### Some platform jobs failed during build + +- Check the failed job logs: `https://github.com/boscorat/openstan/actions` +- Common issues: + - **macOS notarisation timeout**: Apple's service occasionally stalls; the workflow retries up to 75 minutes. If it fails, re-run the macOS job from GitHub Actions UI. + - **Windows build timeout**: The WiX toolset can be slow; re-run if it hits the 30-minute timeout. + - **Linux dependency issues**: Check if system libraries are out of date on the runner; typically resolves on next run. +- **Do not publish** if builds are incomplete — delete the partial draft release and push the tag again. + +### Draft release is missing binaries + +- Verify the tag matches the version in `pyproject.toml` +- Check individual job logs to see which platform failed +- Re-run failed jobs from the GitHub Actions UI +- Alternatively, delete the tag, fix the issue, and push a new tag + +### Microsoft WDSI submission rejected + +- Review Microsoft's feedback in the submission portal +- Common rejections: unsigned binary, wrong certificate, or binary has malware signatures (unlikely, but antivirus false positives happen) +- Resubmit or contact Microsoft support if clarification is needed +- Do **not** publish the release until WDSI clears it + +### Release was published but should have been draft + +You can revert a published release to draft: + +```bash +gh release edit v1.2.3 --draft +``` + +This will immediately hide the release from the **Releases** page, but the tag and binaries remain. + +--- + +## Reference: Version Tags + +- **Stable releases**: `v1.0.0`, `v1.2.3` — use semantic versioning +- **Release candidates**: `v1.0.0-rc1`, `v1.0.0-rc2` — include `-rc` suffix +- **Alpha/beta**: `v1.0.0-alpha1`, `v1.0.0-beta2` — include prefix and number +- **Development/test**: `v0.0.0-test` — for testing the release workflow only (delete tag after testing) + +--- + +## Reference: Workflow Files + +- **Main release workflow**: `.github/workflows/release.yml` +- **CI pipeline** (runs on all commits): `.github/workflows/ci.yml` +- **Cleanup** (strips old assets): `.github/workflows/release.yml` (cleanup job) + +--- + +## Related Issues & Documentation + +- **Issue #81**: Release workflow should create draft releases +- **Issue #76**: Review CI Release Pipeline (original checklist) +- **AGENTS.md**: Code signing setup (Windows SignPath, macOS Developer ID) +- **README.md**: Installation and user guide