From 3f896475fb60fcfd831a168fed11b7741e312ccc Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 25 Oct 2026 14:48:10 +0000
Subject: [PATCH] ci(release): publish from a manual run on main (creates the
 tag)

Pushing tags isn't possible from every environment, so the Release
workflow can now also be run by hand on main with 'publish' ticked: it
derives the tag from VERSION and creates it on that commit together with
the release. Tag pushes keep working. Release steps documented in
CONTRIBUTING.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XKGev7S7KWmgSAMGCQtAar
---
 .github/workflows/release.yml | 33 +++++++++++++++++++++++----------
 CONTRIBUTING.md               | 16 ++++++++++++++++
 2 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index dcdddf8..120bdc9 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,8 +1,10 @@
 name: Release
 
-# Push a tag like v2.0.0 (matching VERSION in server/adminpdf/config.py) to
-# build both packages, start each one as a smoke test, and publish a GitHub
-# release with them. On PRs and manual runs it only builds and tests them.
+# Builds both packages, starts each one as a smoke test, and publishes a GitHub
+# release v<VERSION> (VERSION from server/adminpdf/config.py) with them when
+# either a matching tag is pushed or the workflow is run by hand on main with
+# "publish" ticked (the release then creates the tag on that commit).
+# On PRs it only builds and tests the packages.
 on:
   push:
     tags: ["v*"]
@@ -10,6 +12,11 @@ on:
   pull_request:
     paths: ["scripts/**", ".github/workflows/release.yml", "server/pyproject.toml"]
   workflow_dispatch:
+    inputs:
+      publish:
+        description: "Publish release v<VERSION> from this commit (creates the tag)"
+        type: boolean
+        default: false
 
 permissions:
   contents: read
@@ -96,17 +103,21 @@ jobs:
 
   publish:
     name: Publish release
-    if: startsWith(github.ref, 'refs/tags/v')
+    if: startsWith(github.ref, 'refs/tags/v') || (inputs.publish && github.ref == 'refs/heads/main')
     needs: [windows, python]
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
       - uses: actions/checkout@v6
-      - name: Check tag matches VERSION
+      - name: Release tag from VERSION
+        id: tag
         run: |
-          version=$(sed -n 's/^VERSION = "\(.*\)"/\1/p' server/adminpdf/config.py)
-          test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != v$version"; exit 1; }
+          tag="v$(sed -n 's/^VERSION = "\(.*\)"/\1/p' server/adminpdf/config.py)"
+          if [ "$GITHUB_REF_TYPE" = tag ] && [ "$GITHUB_REF_NAME" != "$tag" ]; then
+            echo "tag $GITHUB_REF_NAME != $tag"; exit 1
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
       - uses: actions/download-artifact@v5
         with:
           path: dist
@@ -114,10 +125,12 @@ jobs:
       - name: Publish
         env:
           GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.tag.outputs.tag }}
         run: |
-          python3 scripts/release_notes.py "$GITHUB_REF_NAME" > notes.md
+          python3 scripts/release_notes.py "$TAG" > notes.md
           ls -l dist
-          gh release create "$GITHUB_REF_NAME" dist/*.zip \
-            --title "$GITHUB_REF_NAME — Admin PDF Toolkit 2" \
+          gh release create "$TAG" dist/*.zip \
+            --target "$GITHUB_SHA" \
+            --title "$TAG — Admin PDF Toolkit 2" \
             --notes-file notes.md \
             --latest
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 934d2b6..097c9a1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -56,6 +56,14 @@ cd web && npm run check && npm run build
 - Keep the UI keyboard-accessible; the WCAG 2.1 AA audit (`web/e2e/a11y.mjs`) runs in CI.
 - Fill in the PR template; explain the *why*.
 
+### Releasing
+
+1. Set `VERSION` in `server/adminpdf/config.py` (and `server/pyproject.toml`, `web/package.json`)
+   and move `[Unreleased]` in `CHANGELOG.md` to a `[x.y.z]` section; merge to `main`.
+2. Run the **Release** workflow on `main` with *publish* ticked (Actions → Release → Run workflow),
+   or push a `vX.Y.Z` tag. It builds the self-contained Windows package and the Linux/macOS package,
+   starts both as a smoke test and publishes the GitHub release (creating the tag if needed).
+
 ### Licensing
 
 By contributing you agree that your contribution is licensed under AGPL-3.0. Only free / open-source
@@ -106,6 +114,14 @@ cd web && npm run check && npm run build
 - Kullanıcıya görünen metinler **hem Türkçe hem İngilizce**.
 - Arayüz klavyeyle kullanılabilir kalmalı; WCAG 2.1 AA denetimi CI'da çalışır.
 
+### Sürüm çıkarma
+
+1. `server/adminpdf/config.py` içindeki `VERSION`'ı (ve `server/pyproject.toml`, `web/package.json`)
+   güncelleyin, `CHANGELOG.md`'de `[Unreleased]` bölümünü `[x.y.z]` yapın; `main`'e birleştirin.
+2. `main` üzerinde **Release** iş akışını *publish* işaretli çalıştırın (Actions → Release → Run
+   workflow) ya da `vX.Y.Z` etiketi gönderin. Windows paketi ve Linux/macOS paketi derlenir, ikisi de
+   açılıp denenir ve GitHub release'i yayımlanır (etiket yoksa oluşturulur).
+
 ### Lisans
 
 Katkılarınız AGPL-3.0 ile lisanslanır. Yalnızca AGPL-3.0 uyumlu ücretsiz/açık kaynak bağımlılıklar