[docs] Add /backport-docs skill for release-branch doc cherry-picks

docs.ray.io/en/latest is built from the newest releases/X.Y.Z branch, not
master, so a docs change merged to master only reaches /latest once it's
cherry-picked onto the release branch.

Add a shared Claude Code skill that walks through that backport end to end:
find the release branch, identify what's missing, skip already-backported
content, cherry-pick with -x --signoff, verify cross-references and toctree
entries for the fail_on_warning build, and open a draft cherry-pick PR. Also
document the process for humans in the docs contribution guide, and register
the skill in the agent-development guide and the docs-scoped skill list.

Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

Author: dstrodtman

.claude/skills/backport-docs/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: backport-docs
+description: Cherry-pick documentation changes from master onto a release branch so they appear on the docs.ray.io /latest build
+---
+
+# Backport docs to a release branch
+
+`docs.ray.io/en/latest` is built from the newest `releases/X.Y.Z` branch, **not**
+from `master`. A docs change merged to `master` shows up only on
+`docs.ray.io/en/master` until it's cherry-picked onto the release branch. Use this
+skill to get already-merged docs onto `/latest`.
+
+Throughout, `<remote>` is the remote that points at `ray-project/ray`. Derive it
+from `git remote -v` — it's `origin` in a direct clone and `upstream` in a clone
+that started as a fork. Don't assume.
+
+## 1. Find the release branch that `/latest` serves
+
+```bash
+git ls-remote --heads <remote> 'refs/heads/releases/*' | sort -t/ -k3 -V | tail -5
+```
+
+The highest `releases/X.Y.Z` version is what `/latest` tracks. Fetch it:
+
+```bash
+git fetch <remote> releases/X.Y.Z
+```
+
+## 2. Identify what's missing on `/latest`
+
+You usually start from a set of already-merged master commits or PRs (for example,
+the docs behind a release blog post). For each candidate, check whether it — or
+equivalent content — is already on the release branch:
+
+- **File missing entirely:**
+  `git cat-file -e <remote>/releases/X.Y.Z:doc/source/<path>.md`
+- **File present but content differs:**
+  `git diff <remote>/releases/X.Y.Z..<remote>/master -- doc/source/<path>.md`
+- **Which master commits touch a page (newest first):**
+  `git log --oneline --no-merges <remote>/releases/X.Y.Z..<remote>/master -- doc/source/<path>.md`
+
+## 3. Check for prior backports (avoid duplicates)
+
+Equivalent content is often already on the release branch under a **different SHA**
+(a prior cherry-pick). Re-applying it will conflict or produce an empty commit.
+Before picking a PR, search the release-branch history for it:
+
+```bash
+git log --oneline <remote>/releases/X.Y.Z --grep "#<PR_NUMBER>)"
+```
+
+If it's already there, skip that commit. Confirm with a file diff
+(`git diff <remote>/releases/X.Y.Z..<remote>/master -- <path>`); an empty diff means
+the page is already up to date on `/latest`.
+
+Also check nothing is already in flight:
+
+```bash
+gh pr list --repo ray-project/ray --state open --base releases/X.Y.Z
+gh pr list --repo ray-project/ray --state open --search "<PR_NUMBER> in:title,body"
+```
+
+## 4. Cherry-pick onto a worktree of the release branch
+
+```bash
+git worktree add -b <branch> .worktrees/<branch> <remote>/releases/X.Y.Z
+cd .worktrees/<branch>
+```
+
+Apply the chosen commits in **chronological (oldest-first)** order, preserving
+provenance (`-x`) and DCO sign-off (`--signoff`, required — see
+`doc/source/ray-contribute/agent-development.md`):
+
+```bash
+git cherry-pick -x --signoff <sha1> <sha2> ...
+```
+
+**Keep the backport tight.** Cherry-pick only the feature/fix commits. Leave out
+broad, non-feature commits that happen to touch the same files (site-wide
+frontmatter/SEO passes, terminology renames, tooling like vendored references).
+Their hunks will remain as harmless residual diffs against master.
+
+### Resolving conflicts
+
+Conflicts here almost always come from an **excluded** commit that the picked
+commit carried as adjacent context (for example, `html_meta` frontmatter the
+release branch doesn't have). Resolve toward the release branch's state for those
+excluded hunks, and keep only the feature substance. If the whole page turns out to
+be already backported (step 3), `git cherry-pick --skip` it.
+
+## 5. Verify the build won't break
+
+The docs build runs with `fail_on_warning: true` (`.readthedocs.yaml`), so an
+unresolved cross-reference or a toctree entry pointing at a nonexistent file fails
+the build. For every file the backport changed:
+
+- **Cross-references resolve on the branch.** Collect the `{ref}` and `{doc}`
+  targets and confirm each label exists:
+  ```bash
+  git grep -nE "^\(<label>\)=" -- 'doc/source/**'   # MyST label
+  git grep -nE "^\.\. _<label>:" -- 'doc/source/**'  # rST label
+  ```
+- **New toctree entries point at files that exist** on the branch.
+- Sanity-check that each changed file matches master except for the hunks you
+  intentionally excluded:
+  `git diff HEAD..<remote>/master -- <path>`.
+
+A local docs build (see the "Building the Ray documentation" section of
+`doc/source/ray-contribute/docs.md`) is the strongest check before handing off.
+
+## 6. Open the PR
+
+Push the branch to `ray-project/ray` (not a fork, if you have push access) and open
+against the release branch:
+
+```bash
+git push -u <remote> <branch>
+gh pr create --repo ray-project/ray \
+  --base releases/X.Y.Z --head <branch> --draft \
+  --title "[cherry-pick][X.Y.Z][docs] <summary>" \
+  --body-file <body>
+```
+
+- Match the release branch's existing title convention: `[cherry-pick][X.Y.Z]...`.
+- Open as **draft** — Ray's contribution policy requires a human to review every
+  line and run tests before it requests review.
+- The PR body must state why it isn't a duplicate, what testing ran, and that AI
+  assistance was used (see `AGENTS.md`). Note any commits you deliberately excluded
+  and any already-present backports you skipped.
+- Keep internal tracking keys out of the PR title, body, and commits.

doc/.claude/CLAUDE.md

@@ -61,5 +61,6 @@ For regression checks, compare a PR preview against `/en/master` — it's the do
 
 - `/lint` — run linters on modified files.
 - `/fetch-buildkite-logs` — pull build logs for CI failures.
+- `/backport-docs` — cherry-pick merged docs onto the release branch so they appear on `docs.ray.io/en/latest`.
 
 See top-level `.claude/CLAUDE.md` for the full skill index.

doc/source/ray-contribute/agent-development.md

@@ -28,7 +28,7 @@ The Ray repository includes shared Claude Code configuration that is version-con
 - `.claude/CLAUDE.md`: root instructions loaded in every session
 - `<library>/.claude/CLAUDE.md`: library-specific instructions loaded on-demand (for example, `python/ray/data/.claude/CLAUDE.md`)
 - `.claude/rules/`: coding rules scoped by file type
-- `.claude/skills/`: reusable workflows (rebuild, lint, fetch CI logs)
+- `.claude/skills/`: reusable workflows (rebuild, lint, fetch CI logs, backport docs)
 - `.claude/agents/`: project-specific subagents
 
 Personal configuration lives in files that are **not** version-controlled:
@@ -110,6 +110,7 @@ Shared skills available in every session:
 - `/rebuild`: guided Ray rebuild based on what files changed
 - `/lint`: run linting and formatting checks
 - `/fetch-buildkite-logs`: fetch and analyze Buildkite CI logs
+- `/backport-docs`: cherry-pick merged docs onto a release branch so they appear on `docs.ray.io/en/latest`
 
 ### Adding team rules
 

doc/source/ray-contribute/docs.md

@@ -441,6 +441,20 @@ If you run into a problem building the docs, following these steps can help isol
 4. **Enable breakpoints in Sphinx.** Add `-P` to the `SPHINXOPTS` in `doc/Makefile` to tell `sphinx` to stop when it encounters a breakpoint, and remove `-j auto` to disable parallel builds. Now you can put breakpoints in the modules you're trying to import, or in `sphinx` code itself, which can help isolate stubborn build issues.
 5. **[Incremental build] Side navigation bar doesn't reflect new pages.** If you're adding new pages, they should always show up in the side navigation bar on index pages. However, incremental builds with `make local` skip rebuilding many other pages, so Sphinx doesn't update the side navigation bar on those pages. To build docs with a correct side navigation bar on all pages, consider using `make develop`.
 
+(backport-docs-to-release)=
+
+## Getting a docs change onto the released version
+
+`docs.ray.io/en/latest` is built from the newest `releases/X.Y.Z` branch, not from `master`. A docs change merged to `master` appears on `docs.ray.io/en/master` right away, but only reaches the default `/latest` site once it's cherry-picked onto the current release branch.
+
+If a merged docs change should be live on the released version — for example, documentation for a feature that has already shipped — open a cherry-pick pull request against the `releases/X.Y.Z` branch:
+
+- Base the PR on `releases/X.Y.Z` and title it `[cherry-pick][X.Y.Z][docs] ...` to match the branch's convention.
+- Apply the commits with `git cherry-pick -x --signoff` to preserve provenance and the required DCO sign-off.
+- Before you start, check that the change isn't already backported under a different commit (`git log --oneline releases/X.Y.Z --grep "#<PR>)"`) and that no cherry-pick PR is already open against the branch.
+
+If you use Claude Code, the `/backport-docs` skill walks through this end to end, including the build-safety checks. See {ref}`agent-development`.
+
 ## Where to go from here?
 
 There are many ways to contribute to Ray other than documentation. See {doc}`our contributor guide <getting-involved>` for more information.