Skip to content

[docs] Add contributor guide for editing and managing Python dependencies#63547

Open
ans9868 wants to merge 4 commits into
ray-project:masterfrom
ans9868:docs/dependency-management
Open

[docs] Add contributor guide for editing and managing Python dependencies#63547
ans9868 wants to merge 4 commits into
ray-project:masterfrom
ans9868:docs/dependency-management

Conversation

@ans9868
Copy link
Copy Markdown
Contributor

@ans9868 ans9868 commented May 20, 2026

Summary

Adds a contributor guide for editing and managing Ray's Python dependencies. Covers the three-layer architecture (source files → compiled requirements → per-image lock files), how to add or update a dependency, how to diagnose conflicts with uv vs pip, and the edge cases that bite contributors (ARM64 skip, platform-specific CPU vs GPU wheels, Wanda Docker cache invalidation, requirements.txtsetup.py sync requirement).

Why

Completes item 4 of #60512. I had to map out the dependency structure and hit most of the gotchas described here while landing #60522 (modernizing AxSearch for ax-platform 1.0+). This doc is meant to keep the next contributor out of those holes.

Scope

Two files, pure docs change. No build-system changes, no lock regeneration needed.

  • doc/source/ray-contribute/dependency-management.md (new)
  • doc/source/ray-contribute/getting-involved.rst (one-line toctree entry)

The page slots into the Getting Involved / Contributing sidebar between "CI Testing Workflow on PRs" and "Contributing to the Ray Documentation."

Built locally with make develop under -W (warnings-as-errors). There are no Sphinx warnings on the new file.

Miscellaneous

The framing of this doc borrows from @elliot-barn's ray-dependencies skill on the elliot-barn-dependencies-skill branch, especially the requirements.txtsetup.py sync rule.

@aslonnie / @elliot-barn -- you were both deep in the dependency issues during #60522 (and the related side-quest PRs I opened along the way, #62596 and #62471). Happy to have either of you review if you have time.

…cies

Signed-off-by: Adel Nour <ans9868@nyu.edu>
@ans9868 ans9868 requested a review from a team as a code owner May 20, 2026 18:14
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new documentation guide, dependency-management.md, which provides a comprehensive overview of Ray's three-layer Python dependency structure (Source, Compiled, and Locks). It also includes instructions for updating dependencies and troubleshooting resolution conflicts using tools like uv. The review feedback identifies minor typographical errors, trailing whitespace, and capitalization inconsistencies for terms like 'Python', 'Ray', and 'uv'.

Comment thread doc/source/ray-contribute/dependency-management.md Outdated
Comment thread doc/source/ray-contribute/dependency-management.md Outdated
Comment thread doc/source/ray-contribute/dependency-management.md Outdated
@ray-gardener ray-gardener Bot added docs An issue or change related to documentation core Issues that should be addressed in Ray Core community-contribution Contributed by the community labels May 20, 2026
ans9868 and others added 3 commits May 20, 2026 22:03
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: Nour999 <130527901+ans9868@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: Nour999 <130527901+ans9868@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: Nour999 <130527901+ans9868@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

community-contribution Contributed by the community core Issues that should be addressed in Ray Core docs An issue or change related to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant