docs: add a backporting policy to the contributor guide

[andygrove]

Which issue does this PR close?

There is no issue for this. It comes out of checking, before 1.1.0-rc1, whether anything backported to branch-1.0 was missing from branch-1.1.

Rationale for this change

Two release branches take backports right now: branch-1.0 for 1.0.1 and branch-1.1 for 1.1.0. Nothing written down said that a fix going to an older release branch also has to reach the newer ones, or how to check that before a release. A fix that ships in 1.0.1 but not in 1.1.0 is a regression for anyone who upgrades.

I checked all 25 commits on branch-1.0 since it was cut. Every fix is on branch-1.1, either because it merged to main before the cut or through its own backport. One change isn't: the CI fix in #6277 that makes the Iceberg jobs take Comet from the local Maven repository instead of Maven Central. It went to branch-1.0 inside the backport of #6219, an unrelated fix, and didn't reach main or branch-1.1. branch-1.1 won't need it until 1.1.0 is on Maven Central.

What changes are included in this PR?

• A new page, docs/source/contributor-guide/backporting.md. It covers:
  • Which branches take backports. Normally that's the branch of the latest release, plus the new branch until its .0 release ships. An older line can take a fix when the maintainers decide it's worth it, with no fixed cutoff.
  • What qualifies, judged by the issue a pull request closes rather than by its title prefix.
  • The rule that a fix going to one release branch also goes to every newer one, and that the older backport doesn't merge before the newer one is ready.
  • Changes that start on a release branch. Send them to main too, or say why not, and never bundle them into the backport of an unrelated fix.
  • How to open a backport: cherry-pick -x, one source pull request per backport, the [branch-N.M] title the branch-1.1 backports already use, and every adaptation listed in the description. It also lists what differs on a release branch and is easy to miss.
  • A shell check to run before a release. It uses the -x trailers to list fixes on an older branch that a newer one lacks.
• release_process.md gets a checklist step and a "Check for Missing Backports" section before the change log. It also creates the branch's backport-N.M label when the branch is cut.
• versioning_policy.md: the Release Cadence section said Comet doesn't backport fixes to older minor releases. It now says patch releases normally come from the latest minor, the maintainers may still backport an important fix to an older one, and it links the new page.
• The contributor guide index and AGENTS.md link to the new page.

How are these changes tested?

• npx prettier@latest --check passes on the changed files.

• A local Sphinx build gives the same 63 warnings as main, so every new link and anchor resolves. The page renders under Project Mechanics.

• ./mvnw -N apache-rat:check reports 0 unknown licenses.

• I ran the page's check as written, under both zsh and bash, against branch-1.0 and branch-1.1. It reports nothing missing, and lists nine commits to check by hand:

  • the three 1.0.0 release commits
  • three changes made only on branch-1.0: docs: correct Spark 4.2 version and CI test status in installation guide (branch-1.0) #5316, ci: [branch-1.0] deploy the website only from main #6229 and fix: [branch-1.0] build the Spark 3.4 and 3.5 jars for Java 11 on any JDK #6285
  • three backports made without -x: fix: [branch-1.0] apply the parent struct's null mask before hashing its fields (#5754) #5823, fix: [branch-1.0] read shuffle write buffer, spill limit and off-heap sizes in bytes (#6191) #6209 and test: [branch-1.0] wait for Parquet write plan callbacks (#6108) #6338

  I checked all nine by hand. Against branch-1.1 as it stood at the cut, before fix: [branch-1.1] Native S3 scan on EKS/IRSA turns a transient STS throttle into a hard 403 storm (#6025) #6323, the check reports fix: Native S3 scan on EKS/IRSA turns a transient STS throttle into a hard 403 storm #6025 as missing.

[sunchao]

Summary

• Prior state and problem: Backport eligibility and propagation across release branches lacked documented guidance, risking fixes being lost when users upgrade.
• Design approach: Adds a backport policy and connects it to the release checklist, versioning policy, contributor navigation, and agent guidance.
• Correctness / compatibility analysis: No introduced P1/P2 issues found within this review. No Comet/Spark execution, supported-version behavior, or runtime overhead changes. Existing discussions were checked and contain no unresolved concerns.
• Key design decisions: Requires newer branches to receive fixes, preserves source commit identities with cherry-pick -x, and separates unrelated release-branch changes. The history-based audit explicitly documents its limitations.
• Implementation sketch: Five documentation files add policy, examples, links, and a shell check without introducing production abstractions.
• Behavioral changes worth calling out: Maintainers gain backport labels, adaptation-reporting requirements, and a pre-release check for missing fixes.
• Suggested improvements: None meeting the P1/P2 reporting threshold.

Reviewed the entire diff from e1d2c11729c2fc60a5def4e87bb17e5b28df2a29 to fb6e0ec5693b4d0c24cdc530da757d386d943550. Confirmed the PR remains non-draft. Routed skill: review-comet-pr; no sibling skill applies.

Exact-head CI: No failed checks. Preflight passed, including license and Markdown checks. Build, Spark SQL, Iceberg, and site deployment jobs were skipped.

Validation: The documented shell check passed disposable Git-history tests under Bash and Zsh for inherited fixes, existing and missing backports, multiple source trailers, and manual-review commits. Added local links and anchors resolve; git diff --check passed. Sphinx rendering and JVM/native builds were not run. The release-branch audit was tested with fixtures, not live release histories.