docs: update contributing guidelines to clarify release automation and required secrets

Author: krypton-byte

.github/workflows/CI.yml

@@ -2,9 +2,6 @@ name: CI
 
 on:
   push:
-    branches:
-      - main
-      - master
     tags:
       - "v*"
   pull_request:
@@ -221,16 +218,45 @@ jobs:
       id-token: write
       contents: read
     steps:
+      - name: Log release context
+        run: |
+          echo "event=${GITHUB_EVENT_NAME}"
+          echo "ref=${GITHUB_REF}"
+          echo "sha=${GITHUB_SHA}"
+
       - name: Download wheel artifacts
         uses: actions/download-artifact@v4
         with:
           pattern: wheels-*
           merge-multiple: true
           path: dist
+
+      - name: Ensure PyPI token exists
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          if [ -z "${UV_PUBLISH_TOKEN}" ]; then
+            echo "::error::Missing PYPI_API_TOKEN secret."
+            exit 1
+          fi
+
+      - name: Validate release artifacts
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          files=(dist/*)
+          if [ ${#files[@]} -eq 0 ]; then
+            echo "::error::No artifacts found in dist/."
+            exit 1
+          fi
+          printf '%s\n' "${files[@]}"
+
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+
       - uses: astral-sh/setup-uv@v5
+
       - name: Publish artifacts
         run: uv publish dist/*
         env:

.github/workflows/release.yml

@@ -1,9 +1,11 @@
 name: Semantic Release
 
 on:
-  push:
+  pull_request:
     branches:
       - main
+    types:
+      - closed
   workflow_dispatch:
 
 permissions:
@@ -15,30 +17,87 @@ concurrency:
 
 jobs:
   release:
-    if: github.actor != 'github-actions[bot]'
+    if: >-
+      ${{
+        github.event_name == 'workflow_dispatch' ||
+        (
+          github.event_name == 'pull_request' &&
+          github.event.pull_request.merged == true &&
+          github.event.pull_request.base.ref == 'main' &&
+          github.event.pull_request.head.ref == 'dev'
+        )
+      }}
     runs-on: ubuntu-latest
     steps:
+      - name: Log trigger context
+        run: |
+          echo "event=${GITHUB_EVENT_NAME}"
+          echo "ref=${GITHUB_REF}"
+          echo "actor=${GITHUB_ACTOR}"
+          echo "pr_merged=${{ github.event.pull_request.merged }}"
+          echo "pr_base=${{ github.event.pull_request.base.ref }}"
+          echo "pr_head=${{ github.event.pull_request.head.ref }}"
+
+      - name: Ensure release push token exists
+        env:
+          RELEASE_PUSH_TOKEN: ${{ secrets.RELEASE_PUSH_TOKEN }}
+        run: |
+          if [ -z "${RELEASE_PUSH_TOKEN}" ]; then
+            echo "::error::Missing RELEASE_PUSH_TOKEN secret."
+            exit 1
+          fi
+
       - uses: actions/checkout@v4
         with:
+          ref: main
           fetch-depth: 0
           submodules: recursive
+          persist-credentials: false
 
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
 
       - uses: astral-sh/setup-uv@v5
 
+      - name: Configure authenticated remote
+        env:
+          RELEASE_PUSH_TOKEN: ${{ secrets.RELEASE_PUSH_TOKEN }}
+        run: git remote set-url origin "https://x-access-token:${RELEASE_PUSH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+
       - name: Configure git identity
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
+      - name: Capture release baseline
+        id: baseline
+        run: |
+          echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+          echo "tag=$(git describe --tags --abbrev=0 2>/dev/null || true)" >> "$GITHUB_OUTPUT"
+
       - name: Run semantic release
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.RELEASE_PUSH_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.RELEASE_PUSH_TOKEN }}
         run: uv run --no-project --with python-semantic-release==9.21.1 semantic-release version
 
       - name: Push release commit and tags
         run: git push --follow-tags origin HEAD:main
+
+      - name: Summarize release outcome
+        run: |
+          set -euo pipefail
+          after_sha=$(git rev-parse HEAD)
+          after_tag=$(git describe --tags --abbrev=0 2>/dev/null || true)
+
+          echo "before_sha=${{ steps.baseline.outputs.sha }}"
+          echo "after_sha=${after_sha}"
+          echo "before_tag=${{ steps.baseline.outputs.tag }}"
+          echo "after_tag=${after_tag}"
+
+          if [ "${after_sha}" = "${{ steps.baseline.outputs.sha }}" ] && [ "${after_tag}" = "${{ steps.baseline.outputs.tag }}" ]; then
+            echo "No new release generated from this merge."
+          else
+            echo "Release generated. Latest tag: ${after_tag:-none}"
+          fi

CONTRIBUTING.md

@@ -89,6 +89,12 @@ Include:
 
 ## Release Flow Overview
 
-- Every merge to `main` is evaluated by semantic release.
-- If commits qualify (`feat`, `fix`, `perf`, or breaking), version and changelog are updated automatically.
-- New tags (`vX.Y.Z`) trigger multi-platform wheel builds and PyPI publish.
+- Release automation runs when a PR from `dev` into `main` is merged.
+- Semantic release evaluates Conventional Commits from merged changes.
+- If commits qualify (`feat`, `fix`, `perf`, or breaking), version and changelog are updated and a new tag (`vX.Y.Z`) is created.
+- If commits do not qualify (for example docs/chore only), release is a no-op and no publish is triggered.
+- New `vX.Y.Z` tags trigger the CI workflow that builds multi-platform wheels and publishes to PyPI.
+
+Required repository secrets:
+- `RELEASE_PUSH_TOKEN`: personal access token used by semantic-release workflow to push release commit and tags.
+- `PYPI_API_TOKEN`: token used by publish job to upload wheels/sdist to PyPI.