[sentry-junior]

Scope: whole repo, no audience filter. Part of a devinfra docs refresh.

Files

• README.md: rewritten for end users only (requirements, install, commands, env vars, config reference, help, license). The ## Dev section moved out.
• AGENTS.md (new): thin router with setup, test, and lint commands, the one invariant, and a code map. This holds the dev commands that used to be in README.
• 9 source files under devservices/: deleted 25 comment lines that only narrated the next line. One of them was wrong: SupervisorManager.get_all_process_info said "Check if supervisor client is up" above a has_programs check. No code changed.
• Not touched: CHANGELOG.md (dated record), LICENSE.md, testing/resources/*/README.md (fixtures).

Markdown lines went from 178 to 183. Cutting the long YAML comments saved space, and that space went to commands and settings README never documented.

Corrected claims (with code evidence)

• list-services does not list "all available Sentry services". It lists running services, and --all adds stopped services found in the devenv coderoot. It also has the alias ls. See commands/list_services.py.
• status shows one running service and its dependencies, not "all services". See commands/status.py.
• list-dependencies prints only names and descriptions. It does not show "enabled/disabled". See commands/list_dependencies.py.
• purge <service-name> removes all state, cache, containers, and volumes. With a name, it asks for confirmation and purges only that service. See commands/purge.py.
• Added the missing reset command, the global -c/--config flag (it cannot be combined with a service name, per utils/services.py:find_matching_service), up --mode/--offline, and the toggle runtime argument (local|containerized, per utils/state.py:ServiceRuntime).
• Config reference: version must be 0.1 (VALID_VERSIONS). A default mode is required. Dependencies accept only description and remote. All three are enforced in configs/service_config.py. The network comment now says devservices up creates the devservices network (up.py:_create_devservices_network).
• Documented the requirements and environment variables the code depends on: the devenv coderoot in ~/.config/sentry-devenv/config.ini (utils/devenv.py), the Docker Compose >= 2.29.7 auto-install (constants.py), GITHUB_TOKEN/GH_TOKEN/gh auth token (utils/github.py), and DEVSERVICES_DISABLE_SENTRY (main.py).

Load-bearing doc

scripts/bump-version.sh rewrites the devservices==<version> line in README.md and fails if the line is missing. The line is kept exactly once. I ran the script on a temp copy (1.2.4 to 9.9.9) and it exited 0.

Code looks wrong (not changed)

• commands/update.py tells users to run pip install --update -r requirements.txt. pip has no --update flag. It should be --upgrade.
• commands/reset.py declares service_name optional (nargs="?") but never falls back to the current directory. Without a name, it filters on com.docker.compose.service=None and fails. The README documents the name as required in practice.
• pyproject.toml describes the integration marker as "run in CI only", but nothing skips those tests locally. pytest -n4 runs them too.

Could not verify

• That the config example's comments match every supervisor program setting accepted by x-programs. I only checked that command is the field serve reads.

Candidates to enforce

• Exposing service ports only on 127.0.0.1 and the orchestrator=devservices label are documented requirements. No validation in service_config.py checks them.

Checks run

• test -e on every relative link and backticked path in the changed docs: all resolve.
• git diff --check: clean. Python AST parse of the edited source files: ok.
• bump-version.sh dry run on a copy: ok.
• Not run: pre-commit (ruff, mypy, shellcheck) and pytest. The sandbox has no uv or pip. The source changes only delete comments.

via @joshuarli.

--

View Junior Session [Sentry]