From ccc80e7253b2a01431a5cc20f707c23c75ae3163 Mon Sep 17 00:00:00 2001
From: Dominik Jain <dominik.jain@oraios-ai.de>
Date: Mon, 11 May 2026 21:26:38 +0200
Subject: [PATCH] Improve release mechanism (two stages: draft release +
 publish to PyPi upon conversion)

---
 .github/workflows/create-release.yml | 19 +++++++++++++++++++
 .github/workflows/publish.yml        | 17 +++++------------
 README-dev.md                        | 14 +++++++++++---
 3 files changed, 35 insertions(+), 15 deletions(-)
 create mode 100644 .github/workflows/create-release.yml

diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml
new file mode 100644
index 00000000..05dc1d11
--- /dev/null
+++ b/.github/workflows/create-release.yml
@@ -0,0 +1,19 @@
+name: Create Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  create-release:
+    name: Create a candidate release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          draft: true
+          body: "See [change log](https://github.com/oraios/serena/blob/main/CHANGELOG.md)"
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 309d7a00..c8b53959 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -1,10 +1,9 @@
 name: Publish Python Package
 
 on:
-  push:
-    # Sequence of patterns matched against refs/tags
-    tags:
-      - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
+  release:
+    types:
+      - published
 
 jobs:
   publish:
@@ -12,11 +11,11 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       id-token: write  # Required for trusted publishing
-      contents: write  # Required for the GH release
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
+          ref: ${{ github.event.release.tag_name }}
           persist-credentials: false
 
       - name: Install the latest version of uv
@@ -27,11 +26,5 @@ jobs:
       - name: Build package
         run: uv build
 
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v3
-        with:
-          files: |
-            dist/*.tar.gz
-            dist/*.whl
-      - name: Publish to PyPI (conditional)
+      - name: Publish to PyPI
         run: uv publish
diff --git a/README-dev.md b/README-dev.md
index cd5fce8f..50a12340 100644
--- a/README-dev.md
+++ b/README-dev.md
@@ -7,14 +7,22 @@ and tools for formatting and type checking.
 
 ## Release Process
 
-1. Ensure clean git status
-2. Set version for release, e.g.
+1. Ensure clean git status.
+2. Set the version for release, e.g.
    
        python scripts/bump_version.py --patch
        python scripts/bump_version.py --minor
 
    This also creates the git tag.
-3. Push to GitHub, triggering the release process.
+3. Push to GitHub:
 
        git push
        git push --tags
+
+   Pushing the tag triggers the `create-release` workflow, which creates a
+   **draft release** on GitHub.
+4. Review the draft release on the
+   [GitHub Releases page](https://github.com/oraios/serena/releases).
+   When ready, publish it (click *Publish release*).
+   This triggers the `publish` workflow, which builds and publishes the
+   package to PyPI.
\ No newline at end of file