[sentry-junior]

Docs refresh. Docs only, no behavior changes.

Scope: whole repo, no audience filter.

Files

• README.md: now covers end users only. It explains how to use the index (URL, wheels only, only versions in packages.ini, supported Pythons and platforms), has a numbered how-to for adding a package (what add_pkg does, when CI deploys), and gives the license. The per-option packages.ini reference moved out.
• docs/packages-ini.md (new): the packages.ini option reference that used to be in README, split into build options and validation options. It also notes that format_ini drops # comments and that an unknown option fails the build.
• docs/build-pipeline.md (new): how CI runs build, validate, and deploy, plus hazards. No doc covered this before.
• runbook/deleting.md moved to docs/deleting-packages.md. Nothing referenced the old path, and runbook/ is now empty.
• AGENTS.md (new): a thin router with commands, invariants, and a topic-to-doc map. CLAUDE.md is a symlink to it.
• .claude/skills/upgrade-python/SKILL.md: fixed drift left over from the uv migration (feat: uv #1983). Details below.
• Not changed: PYTHON-3.14-UPGRADE.md. It is a dated record, and the skill names its path pattern (PYTHON-MAJOR.MINOR-UPGRADE.md in the repo root), so it stays in the root.
• Cut: the bold on the approval sentence, the internal-only GitHub team link (the fact itself stays), and the line numbers in the skill.

Claims corrected

• README heading validate_skip_modules is now validate_skip_imports. The code reads validate_skip_imports (validate.py Info.from_dct, build.py Package.make), and the README's own example already used that name.
• The python_versions example used <3.9. PYTHONS in build.py starts at 3.11, so that example could never match. It now uses a real entry, [brotli==1.0.9] python_versions = <3.12, from packages.ini.
• The deletion runbook said Cache-Control: no store, which is not a valid directive. It now says no-store, the value bin/upload-artifacts uses (CACHE_NO).
• Skill: dropped the step that edits python3.11 -m venv /venv in the Dockerfile. That line no longer exists. docker/Dockerfile now builds /venv with uv sync.
• Skill: the macOS PATH entry was $PWD/venv/bin. build.yml uses $PWD/.venv/bin.
• Skill: the temporary image job had no cp pyproject.toml uv.lock docker/ step. docker/Dockerfile copies those files (COPY pyproject.toml uv.lock /tmp/build/), and image.yml runs that cp before docker buildx build, so the job as written would fail to build.
• Skill: replaced stale line numbers with symbol names (PYTHONS is now on line 36 of build.py and line 20 of validate.py).
• Skill: "Without --upgrade-python, builds fail on first error" was not fully true. On Python 3.14, build.py main() and validate.py main() print !!! WARNING (py3.14) and continue.

Claims I could not verify

• The README rule that anyone in the getsentry Engineering team on GitHub can approve PRs. The repo has no CODEOWNERS file. I kept the claim.
• The note at the end of docs/deleting-packages.md that a stale index link "will be cleaned up on the next execution". That depends on how dumb-pypi regenerates pages.
• Whether single-version mode in the skill needs to pin the interpreter for /venv. The old Dockerfile pinned python3.11. With only the new cpython left on PATH, uv sync may now pick the new Python for the tooling venv.
• README has no "where to get help" section, because I could not confirm a public support channel from the repo.

Code that looks wrong (not changed)

• build.py main() (elif python.version == (3, 14)) and validate.py main() (if python == "python3.14") treat any 3.14 failure as a warning. So 3.14 build and validation failures never fail CI. This looks left over from the 3.14 upgrade. Fix: remove the special cases once 3.14 is fully supported.
• upgrade_all.py main() discards subprocess.run(...).returncode and always returns 0. A failed add_pkg run passes silently. Fix: return the return code.

Candidates to enforce

• PYTHONS in build.py and validate.py must match VERSIONS in docker/install-pythons (and the PATH entries in docker/Dockerfile and build.yml). A test could assert that these lists agree.
• No # comments in packages.ini. format_ini drops them silently. It could fail when it finds them instead.

Skipped

• Comment review found no comments to delete. All source comments explain quirks or rationale, apart from TODOs, which I did not touch.
• packages.ini and prebuild/ scripts: config, so out of scope.

Checks run

• pre-commit run --files <changed files>: passed (trailing-whitespace and end-of-file-fixer ran; the other hooks had no matching files).
• Link and path check over the changed docs with test -e: all links resolve.
• python -m add_pkg --help and python -m build --help: checked the flags the docs mention.
• uv run coverage run -m pytest tests and uv run coverage report: 86 passed. I ran these to confirm the test command in AGENTS.md.

via @joshuarli.

--

View Junior Session [Sentry]