ci: build pull request RPC docs from the event commit

.github/workflows/rpc-docs-pages.yml

@@ -85,20 +85,20 @@ jobs:
           DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
           DISPATCH_REF: ${{ inputs.ref || '' }}
           EVENT_NAME: ${{ github.event_name }}
-          PULL_REQUEST_NUMBER: ${{ github.event_name == 'pull_request' && github.event.pull_request.number || '' }}
           PULL_REQUEST_SHA: ${{ github.event_name == 'pull_request' && github.sha || '' }}
         run: |
           set -euo pipefail
           development_ref="${DEFAULT_BRANCH}"
-          development_checkout_ref=""
+          # A pull request builds its event merge commit, checked out by hash:
+          # refs/pull/<n>/merge moves whenever the base branch or the pull
+          # request's stack changes, so it can name a different commit by the
+          # time the build job checks it out.
           if [[ "${EVENT_NAME}" == "pull_request" ]]; then
             development_ref="${PULL_REQUEST_SHA}"
-            development_checkout_ref="refs/pull/${PULL_REQUEST_NUMBER}/merge"
           elif [[ "${EVENT_NAME}" == "workflow_dispatch" && -n "${DISPATCH_REF}" ]]; then
             development_ref="${DISPATCH_REF}"
           fi
           echo "ref=${development_ref}" >> "${GITHUB_OUTPUT}"
-          echo "checkout_ref=${development_checkout_ref}" >> "${GITHUB_OUTPUT}"
 
       - name: Determine publication mode
         id: mode
@@ -128,7 +128,6 @@ jobs:
           python3 doc/rpc/versioned_site.py discover \
             --repository "${REPOSITORY}" \
             --development-ref "${DEVELOPMENT_REF}" \
-            --development-checkout-ref "${{ steps.development.outputs.checkout_ref }}" \
             --publisher-sha "${publisher_sha}" \
             --output "${RUNNER_TEMP}/rpc-docs-build-plan.json" \
             --github-output "${GITHUB_OUTPUT}"

doc/rpc/versioned_site.py

@@ -329,7 +329,6 @@ def build_plan(
     development_ref: str,
     publisher_sha: str,
     repository: str,
-    development_checkout_ref: str = "",
     release_resolver: Callable[[dict[str, Any]], str] | None = None,
     development_resolver: Callable[[str], str] = resolve_commit,
 ) -> dict[str, Any]:
@@ -342,7 +341,7 @@ def build_plan(
         "path": "main",
         "source_ref": development_ref,
         "source_sha": development_sha,
-        "source_checkout_ref": development_checkout_ref or development_sha,
+        "source_checkout_ref": development_sha,
     }
     return {
         "schema_version": SCHEMA_VERSION,
@@ -588,7 +587,6 @@ def parse_args() -> argparse.Namespace:
     discover = subparsers.add_parser("discover")
     discover.add_argument("--repository", required=True)
     discover.add_argument("--development-ref", required=True)
-    discover.add_argument("--development-checkout-ref", default="")
     discover.add_argument("--publisher-sha", required=True)
     discover.add_argument("--output", required=True)
     discover.add_argument("--github-output")
@@ -612,7 +610,6 @@ def main() -> int:
         plan = build_plan(
             releases,
             development_ref=args.development_ref,
-            development_checkout_ref=args.development_checkout_ref,
             publisher_sha=args.publisher_sha,
             repository=args.repository,
         )

test/rpc_docs/test_versioned_site.py

@@ -80,7 +80,6 @@ def test_build_plan_adds_development_after_releases(self) -> None:
         plan = versioned_site.build_plan(
             [release("v1.0.0")],
             development_ref="topic/ref",
-            development_checkout_ref="refs/pull/12/merge",
             publisher_sha="2" * 40,
             repository="Qbit-Org/qbit",
             release_resolver=lambda _release: "1" * 40,
@@ -90,9 +89,9 @@ def test_build_plan_adds_development_after_releases(self) -> None:
         self.assertEqual(plan["latest"], "v1.0.0")
         self.assertEqual([entry["id"] for entry in plan["builds"]], ["v1.0.0", "main"])
         self.assertEqual(plan["development"]["source_ref"], "topic/ref")
-        self.assertEqual(
-            plan["development"]["source_checkout_ref"], "refs/pull/12/merge"
-        )
+        # The build checks out the resolved commit itself, never a ref that can move.
+        self.assertEqual(plan["development"]["source_sha"], "3" * 40)
+        self.assertEqual(plan["development"]["source_checkout_ref"], "3" * 40)
         self.assertIn("33333333", plan["development"]["label"])
 
     def test_duplicate_release_tag_is_rejected(self) -> None: