Codex/fix release automation

.github/workflows/release-please.yml → .github/workflows/release.yml

@@ -91,6 +91,48 @@ jobs:
           print-hash: true
           skip-existing: true
 
+      - name: Create core release evidence summary
+        env:
+          CORE_TAG: ${{ needs.release-please.outputs.core_tag }}
+        run: |
+          {
+            echo "# Release Evidence"
+            echo
+            echo "- Core release tag: ${CORE_TAG:-not released}"
+            echo "- Core package tests: passed"
+            echo "- Core package coverage: see \\`coverage-summary.txt\\`"
+          } > release-evidence.md
+
+      - name: Upload core release evidence
+        if: needs.release-please.outputs.core_tag != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CORE_TAG: ${{ needs.release-please.outputs.core_tag }}
+        run: |
+          gh release upload "${CORE_TAG}" \
+            packages/core/dist/* \
+            packages/core/coverage.xml \
+            packages/core/coverage-summary.txt \
+            packages/core/htmlcov.zip \
+            packages/core/CHANGELOG.md \
+            release-evidence.md \
+            --clobber
+
+  build-documentation:
+    needs: release-please
+    if: needs.release-please.outputs.releases_created == 'true'
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      pages: write
+
+    steps:
+      - name: Check out released revision
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-please.outputs.core_tag || github.sha }}
+
       - name: Set up pnpm
         uses: pnpm/action-setup@v4
         with:
@@ -112,10 +154,10 @@ jobs:
       - name: Build documentation site
         working-directory: packages/quickli-docs
         env:
-          QUICKLI_VERSION: ${{ env.QUICKLI_VERSION }}
+          QUICKLI_VERSION: ${{ needs.release-please.outputs.core_tag || 'development' }}
         run: pnpm run build
 
-      - name: Create release evidence summary
+      - name: Create documentation release evidence summary
         env:
           CORE_TAG: ${{ needs.release-please.outputs.core_tag }}
           DOCS_TAG: ${{ needs.release-please.outputs.docs_tag }}
@@ -125,8 +167,6 @@ jobs:
             echo
             echo "- Core release tag: ${CORE_TAG:-not released}"
             echo "- Documentation release tag: ${DOCS_TAG:-not released}"
-            echo "- Core package tests: passed"
-            echo "- Core package coverage: see \\`coverage-summary.txt\\`"
             echo "- Documentation typecheck: passed"
             echo "- Documentation build: passed"
           } > release-evidence.md
@@ -136,21 +176,6 @@ jobs:
         with:
           path: packages/quickli-docs/build
 
-      - name: Upload core release evidence
-        if: needs.release-please.outputs.core_tag != ''
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          CORE_TAG: ${{ needs.release-please.outputs.core_tag }}
-        run: |
-          gh release upload "${CORE_TAG}" \
-            packages/core/dist/* \
-            packages/core/coverage.xml \
-            packages/core/coverage-summary.txt \
-            packages/core/htmlcov.zip \
-            packages/core/CHANGELOG.md \
-            release-evidence.md \
-            --clobber
-
       - name: Upload documentation release evidence
         if: needs.release-please.outputs.docs_tag != ''
         env:
@@ -163,7 +188,7 @@ jobs:
             --clobber
 
   deploy-documentation:
-    needs: build-release-evidence
+    needs: build-documentation
     runs-on: ubuntu-latest
 
     permissions:

CONTRIBUTING.md

@@ -65,5 +65,9 @@ site. Merging a release pull request creates the version tag and GitHub release.
 workflow validates both packages, attaches core-library and documentation release evidence, and
 deploys the documentation site to GitHub Pages.
 
+Use `feat(docs):` for new documentation content and `fix(docs):` for documentation corrections.
+Release Please does not treat the bare `docs:` conventional-commit type as a release-triggering
+change, so using it alone will not create a documentation release.
+
 Maintain package-specific release notes in [packages/core/CHANGELOG.md](packages/core/CHANGELOG.md)
-and [packages/quickli-docs/CHANGELOG.md](packages/quickli-docs/CHANGELOG.md).
+and [packages/quickli-docs/CHANGELOG.md](packages/quickli-docs/CHANGELOG.md).

packages/core/docs/installation.md

@@ -46,4 +46,4 @@ The target support range is Python 3.12, 3.13, and 3.14.
 - The package name is `quickli`.
 - The repository uses the `src` layout.
 - The project is licensed under MIT.
-- Release Please manages versioned releases through `.github/workflows/release-please.yml`.
+- Release Please manages versioned releases through `.github/workflows/release.yml`.

packages/core/docs/open-source-release.md

@@ -23,6 +23,17 @@ core library and documentation site. Merging a Release Please pull request creat
 tag and GitHub release. The release workflow may publish the core package to PyPI when the
 protected `pypi` environment is configured.
 
+PyPI trusted publishing must contain this exact publisher configuration:
+
+- owner: `spmse`
+- repository: `quickli`
+- workflow: `release.yml`
+- environment: `pypi`
+
+The workflow grants `id-token: write` only to the release job and publishes with the official
+PyPA action. A mismatch in any trusted-publisher field causes the upload step to fail before
+PyPI accepts the package.
+
 Governance files now included:
 
 - `CODE_OF_CONDUCT.md`
@@ -49,4 +60,4 @@ Governance files now included:
 
 Release Please is configured in `release-please-config.json` and
 `.release-please-manifest.json`. Release evidence is produced by
-`.github/workflows/release-please.yml`.
+`.github/workflows/release.yml`.

packages/quickli-docs/CHANGELOG.md

@@ -16,5 +16,7 @@ published with the corresponding GitHub release.
 
 ## Unreleased
 
+- Track documentation changes with a release-triggering conventional commit so site updates
+  receive their own Release Please version and GitHub release.
 - Initial release automation and GitHub Pages deployment support.
 - Document core JSON/YAML rendering/loading and add parser concept examples.