Final polishment

Author: vdusek

.github/workflows/manual_release_docs.yaml

@@ -1,17 +1,14 @@
 name: Release docs
 
 on:
-  # Runs when manually triggered from the GitHub UI. Always checks out the default branch —
-  # this workflow pushes a theme-update commit back to the default branch, so the checked-out
-  # ref must be its current tip to avoid non-fast-forward pushes.
+  # Runs when manually triggered from the GitHub UI.
   workflow_dispatch:
 
-  # Runs when invoked by another workflow. The caller is responsible for passing a ref that's
-  # on the default branch tip (e.g. a freshly pushed commit protected by `concurrency: release`).
+  # Runs when invoked by another workflow.
   workflow_call:
     inputs:
       ref:
-        description: Git ref to checkout (must resolve to the default branch tip).
+        description: Git ref to checkout.
         required: true
         type: string
 
@@ -31,20 +28,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Determine checkout ref
-        id: resolve_ref
-        env:
-          INPUT_REF: ${{ inputs.ref }}
-          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
-        run: |
-          REF="${INPUT_REF:-$DEFAULT_BRANCH}"
-          echo "ref=$REF" >> "$GITHUB_OUTPUT"
-
       - name: Checkout repository
         uses: actions/checkout@v6
         with:
           token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
-          ref: ${{ steps.resolve_ref.outputs.ref }}
+          ref: ${{ inputs.ref || github.event.repository.default_branch }}
 
       - name: Set up Node
         uses: actions/setup-node@v6
@@ -73,10 +61,7 @@ jobs:
           add: website/package.json website/yarn.lock
           message: "chore: Automatic docs theme update [skip ci]"
           default_author: github_actions
-          # Required: `actions/checkout` leaves a detached HEAD when invoked with a SHA ref.
-          # Creating a local default-branch pointer at HEAD lets EndBug push it back. The caller
-          # contract (see trigger definitions above) guarantees HEAD is the default branch tip,
-          # so this push is always a fast-forward.
+          # `actions/checkout` detaches HEAD on SHA refs; EndBug needs a branch to push.
           new_branch: ${{ github.event.repository.default_branch }}
 
       - name: Build docs

.github/workflows/manual_release_stable.yaml

@@ -98,7 +98,7 @@ jobs:
           version_number: ${{ needs.release_prepare.outputs.version_number }}
           ref: ${{ needs.changelog_update.outputs.changelog_commitish }}
 
-      # Publishes the package to PyPI using PyPA official GitHub action with OIDC authentication.
+      # Publish the package to PyPI using PyPA official GitHub action with OIDC authentication.
       - name: Publish package to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
 
@@ -109,6 +109,7 @@ jobs:
       contents: write
     uses: ./.github/workflows/manual_version_docs.yaml
     with:
+      # Commit the version docs changes on top of the changelog commit.
       ref: ${{ needs.changelog_update.outputs.changelog_commitish }}
     secrets: inherit
 
@@ -121,6 +122,6 @@ jobs:
       id-token: write
     uses: ./.github/workflows/manual_release_docs.yaml
     with:
-      # Use the version_docs commit to include both changelog and versioned docs.
+      # Commit the docs release changes on top of the version docs commit.
       ref: ${{ needs.version_docs.outputs.version_docs_commitish }}
     secrets: inherit

.github/workflows/manual_version_docs.yaml

@@ -1,22 +1,19 @@
 name: Version docs
 
 on:
-  # Runs when manually triggered from the GitHub UI. Always checks out the default branch —
-  # this workflow pushes the version snapshot commit back to the default branch, so the
-  # checked-out ref must be its current tip to avoid non-fast-forward pushes.
+  # Runs when manually triggered from the GitHub UI.
   workflow_dispatch:
 
-  # Runs when invoked by another workflow. The caller is responsible for passing a ref that's
-  # on the default branch tip (e.g. a freshly pushed commit protected by `concurrency: release`).
+  # Runs when invoked by another workflow.
   workflow_call:
     inputs:
       ref:
-        description: Git ref to checkout (must resolve to the default branch tip).
+        description: Git ref to checkout.
         required: true
         type: string
     outputs:
       version_docs_commitish:
-        description: The commit SHA of the versioned docs commit
+        description: The commit SHA of the versioned docs commit.
         value: ${{ jobs.version_docs.outputs.version_docs_commitish }}
 
 concurrency:
@@ -40,20 +37,11 @@ jobs:
       contents: write
 
     steps:
-      - name: Determine checkout ref
-        id: resolve_ref
-        env:
-          INPUT_REF: ${{ inputs.ref }}
-          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
-        run: |
-          REF="${INPUT_REF:-$DEFAULT_BRANCH}"
-          echo "ref=$REF" >> "$GITHUB_OUTPUT"
-
       - name: Checkout repository
         uses: actions/checkout@v6
         with:
           token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
-          ref: ${{ steps.resolve_ref.outputs.ref }}
+          ref: ${{ inputs.ref || github.event.repository.default_branch }}
 
       - name: Set up Node
         uses: actions/setup-node@v6
@@ -120,10 +108,7 @@ jobs:
           add: website/versioned_docs website/versioned_sidebars website/versions.json
           message: "docs: Version docs for v${{ steps.snapshot.outputs.version }} [skip ci]"
           default_author: github_actions
-          # Required: `actions/checkout` leaves a detached HEAD when invoked with a SHA ref.
-          # Creating a local default-branch pointer at HEAD lets EndBug push it back. The caller
-          # contract (see trigger definitions above) guarantees HEAD is the default branch tip,
-          # so this push is always a fast-forward.
+          # `actions/checkout` detaches HEAD on SHA refs; EndBug needs a branch to push.
           new_branch: ${{ github.event.repository.default_branch }}
 
       - name: Resolve output commitish