ci(docs): fix gh-pages deploy race and align docs workflows with Apache practice

[GOODBOY008]

Purpose of the pull request

Fixes the recurring red Deploy Docusaurus to GitHub Pages runs on main, and aligns the three docs workflows with conventions used by other Apache projects (iceberg, superset).

Most recent occurrence: run 37812706645 (triggered by the Java-only commit a559aa1, #1160) failed at the final push step:

! [remote rejected] gh-pages -> gh-pages (cannot lock ref 'refs/heads/gh-pages':
  is at 51c865a4fbb06713ecf064fb5a7ac95965f96cbe but expected fe5ad2b226766f862c2cae3c71cfa9a76cf07dfa)

Root cause: the deploy workflow triggers on every push to main, and each run takes ~30 minutes (full-history checkout + Docusaurus build). When several PRs merge within a window, multiple deploy runs reach the final git push --force gh-pages concurrently and the losers get rejected by ref-lock contention. On Oct 8 five pushes landed within 24 minutes, and two deploys pushed to gh-pages at the same second.

What's changed?

deploy-docs.yml

• paths filter (website/**, .asf.yaml, the workflow itself): Java-only merges like fix: treat BigDecimal boolean ones by numeric value #1160 no longer trigger a deploy at all — the failing run above would not have existed.
• concurrency: group: deploy-docs with cancel-in-progress: false: genuine docs pushes queue and publish serially instead of racing on the gh-pages ref. Deliberately not cancelling, to avoid killing a publish midway and leaving a half-updated site.
• workflow_dispatch for manual redeploys.
• pnpm store cache via actions/setup-node.
• Least-privilege permissions: workflow-level contents: read, contents: write only on the deploy job (the pattern used by iceberg's site-ci.yml).

ci-docs.yml / preview-docs.yml

• Display names unified to Docs CI / Docs Preview / Docs Deploy, matching the "Docs <role>" style of apache/iceberg (Docs Build CI) and apache/superset (Docs Deployment, Docs Testing).
• Explicit minimal permissions (contents: read; preview additionally pull-requests: write, required by the Netlify action's PR comment).
• persist-credentials: false on checkouts (zizmor hygiene, as in iceberg/superset workflows).
• Each workflow file added to its own path filter.
• preview-docs.yml: added the missing concurrency cancellation, consistent with ci-docs.yml.

Notes:

• fetch-depth: 0 is kept — Docusaurus last-updated timestamps need git history.
• The live site is not stale as a result of the failed run: the losing deploy's commit (fix: treat BigDecimal boolean ones by numeric value #1160) contained no docs changes, so its build output was identical to the winner's.
• No behavior outside the three docs pipelines is affected.

Checklist

• I have read the Contributor Guide.
• I have written the necessary doc or comment.
• I have added the necessary unit tests and all cases have passed. (N/A — CI workflow-only change; YAML syntax validated)

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

🟢 Approval recommended

The workflow changes consistently address the documented deployment race without introducing correctness issues.

0 open findings

🧠 Review effort: Balanced

[delei]

LGTM