Refactor release workflow to improve draft handling and update documentation

Author: dsbilling

.github/workflows/release.yml

@@ -26,8 +26,7 @@ jobs:
           TAG_NAME: ${{ github.ref_name }}
         run: |
           set -euo pipefail
-          release_json="$(gh api "repos/${GITHUB_REPOSITORY}/releases/tags/${TAG_NAME}" 2>/dev/null || true)"
-          if [ -z "$release_json" ]; then
+          if ! release_json="$(gh api "repos/${GITHUB_REPOSITORY}/releases/tags/${TAG_NAME}")"; then
             echo "No release for ${TAG_NAME}. electron-builder will create a draft."
             exit 0
           fi
@@ -37,12 +36,8 @@ jobs:
             echo "Release ${release_id} is already a draft."
             exit 0
           fi
-          echo "Release ${release_id} is published. Converting it to a draft."
-          if gh api -X PATCH "repos/${GITHUB_REPOSITORY}/releases/${release_id}" -f draft=true >/dev/null; then
-            echo "Converted release ${release_id} to a draft."
-            exit 0
-          fi
-          echo "Could not convert it. Deleting the published release (tag stays) so a draft can be created."
+          echo "Release ${release_id} is already published (prerelease or latest). GitHub will not accept more files."
+          echo "Deleting that release. The git tag stays. electron-builder will create a draft."
           gh api -X DELETE "repos/${GITHUB_REPOSITORY}/releases/${release_id}"
 
   package:

docs/contributing.mdx

@@ -43,10 +43,13 @@ Typecheck and build the renderer with `make web-build`. Package installers with
 
 GitHub Actions packages macOS (universal DMG) and Windows (NSIS) when you add a version tag without a `v` prefix. That includes creating the tag in the GitHub UI, or pushing it from git.
 
-1. Set the version you want in `web/package.json`, or let the workflow take it from the tag (`0.1.0`, `0.1.0-alpha.2`).
-2. Create only the git tag, not a published GitHub Release. In the GitHub tags page, or `git tag 0.1.0-alpha.5 && git push origin 0.1.0-alpha.5`.
-3. Wait for **Release desktop**. CI writes installers to a **draft** release. A published or prerelease tag is immutable, so the workflow converts that release to a draft first (or deletes it and recreates the draft).
-4. When both `Dagr_<version>.dmg` and `Dagr_<version>.exe` are attached, publish the draft. For an alpha tag, publish it as a prerelease.
+1. Set the version you want in `web/package.json`, or let the workflow take it from the tag (`0.1.0`, `0.1.0-alpha.7`).
+2. Create **only a git tag**. Do not use “Draft a new release” or publish a prerelease in the GitHub UI first.
+   `git tag 0.1.0-alpha.7 && git push origin 0.1.0-alpha.7`
+3. Wait for **Release desktop**. CI creates a **draft** and attaches the installers.
+4. When both `Dagr_<version>.dmg` and `Dagr_<version>.exe` are on the draft, publish it. For an alpha, publish it as a prerelease.
+
+If you already published a GitHub Release for that tag, CI deletes that release (the tag stays) and creates a draft so the files can be uploaded.
 
 The download site and the in-app update checker only see the latest published, non-prerelease release. Builds are unsigned in this pass.