chore(docs): update PyPI publishing workflow and clarify release process

- Updated the PyPI publishing workflow to indicate that it is now handled by the release-on-tag.yml file, which is the preferred method for publishing to PyPI.
- Added comments to clarify the need for a Trusted Publisher configuration and the limitations of using GITHUB_TOKEN for triggering workflows.
- Enhanced the release-on-tag.yml workflow to include steps for pushing versioned documentation to the main branch and publishing to PyPI, ensuring a streamlined release process.

Author: rithulkamesh

.github/workflows/pypi-publish.yml

@@ -1,5 +1,8 @@
-# Publish hivemind-ai to PyPI when a GitHub release is published.
-# Setup: Configure a Trusted Publisher on PyPI for this repo (no API token needed).
+# Legacy: PyPI is now published from release-on-tag.yml (same workflow as the release).
+# This file is kept for reference. Creating a release with GITHUB_TOKEN does not trigger
+# release:published, so this workflow would not run on tag push. Configure PyPI Trusted
+# Publisher with workflow filename release-on-tag.yml instead.
+#
 # See: https://docs.pypi.org/trusted-publishers/adding-a-published-publisher/
 
 name: Publish to PyPI

.github/workflows/release-on-tag.yml

@@ -1,12 +1,11 @@
-# When you push a version tag (e.g. v1.6.0), create a GitHub Release and open a PR for versioned docs.
-# Note: Creating a release with GITHUB_TOKEN does NOT trigger other workflows (e.g. docs on release),
-# so we run the versioned-docs step here in the same workflow.
+# When you push a version tag (e.g. v1.6.0), create a GitHub Release, push versioned docs to main, and publish to PyPI.
+# Note: Creating a release with GITHUB_TOKEN does NOT trigger other workflows, so we run versioned-docs and PyPI here.
 #
 # Usage:
 #   git tag v1.6.0
 #   git push origin v1.6.0
 #
-# If main has already diverged (e.g. from an older workflow): git fetch origin && git checkout main && git pull --rebase origin main
+# PyPI: Add a Trusted Publisher on PyPI with workflow filename release-on-tag.yml (job: pypi-publish).
 
 name: Release on tag
 
@@ -36,7 +35,6 @@ jobs:
       - name: Extract changelog section
         run: |
           V="${{ steps.version.outputs.version }}"
-          # Match "## [1.6.0]" or "## [1.6.0] - TBD" and print until next ##
           awk -v ver="$V" '
             $0 ~ "^## \\[" ver "\\]" { found=1; next }
             found && /^## \[/ { exit }
@@ -54,12 +52,11 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-  add-version-docs:
+  push-version-docs:
     needs: release
     runs-on: ubuntu-latest
     permissions:
       contents: write
-      pull-requests: write
     steps:
       - name: Checkout main
         uses: actions/checkout@v4
@@ -86,18 +83,34 @@ jobs:
           npm ci
           npx docusaurus docs:version ${{ steps.version.outputs.version }}
 
-      - name: Open PR for versioned docs
-        uses: peter-evans/create-pull-request@v7
+      - name: Push versioned docs to main
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add website/versioned_docs website/versioned_sidebars website/versions.json
+          git diff --staged --quiet || git commit -m "chore(docs): add version ${{ steps.version.outputs.version }}"
+          git push origin HEAD:main
+
+  pypi-publish:
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          branch: "docs/version-${{ steps.version.outputs.version }}"
-          base: main
-          title: "chore(docs): add version ${{ steps.version.outputs.version }}"
-          body: |
-            Versioned docs for **v${{ steps.version.outputs.version }}**. Merge to update the docs site.
-          commit-message: "chore(docs): add version ${{ steps.version.outputs.version }}"
-          add-paths: |
-            website/versioned_docs
-            website/versioned_sidebars
-            website/versions.json
-          delete-branch: true
+          python-version: "3.12"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1