anthropics / anthropics/claude-agent-sdk-python

[Docs] Surface dev-deps install + test/lint commands in README (or add CONTRIBUTING.md)

Open Beginner friendly
#966 1 comment 0 reactions 0 assignees View on GitHub
documentation enhancement good first issue
Dominant language
Python
Stars
8.1k
Forks
1.3k
Avg merge
2d 31m
Merged PRs (30d)
1

Description

## Short description

The README's `## Development` section covers installing the pre-push git hook (`scripts/initial-setup.sh`) but does not document the dev-dependency install command (`pip install -e ".[dev]"`) or the manual lint / typecheck / test commands. Those commands exist in `CLAUDE.md`, which is structured to guide Claude Code agents at runtime, not for human contributors who would naturally look for a `CONTRIBUTING.md`. Adding the missing pieces in the README or as a standalone `CONTRIBUTING.md` would allow external contributors to find the workflow without reverse-engineering it from merged PR history.

## Steps to reproduce

1. Clone the repo and read `README.md` from top to bottom.
2. The `## Development` section says: run `scripts/initial-setup.sh` to install git hooks. The hook runs "lint checks" but the manual command equivalents aren't documented.
3. `pyproject.toml` declares a `dev` extras group (`pytest`, `pytest-asyncio`, `mypy`, `ruff`, `pytest-cov`), but the install command (`pip install -e ".[dev]"`) is not in the README.
4. `CLAUDE.md` documents the manual commands:
- `python -m ruff check src/ tests/ --fix`
- `python -m ruff format src/ tests/`
- `python -m mypy src/`
- `python -m pytest tests/`

These are not surfaced anywhere a human contributor would naturally look.
5. PR title format (Conventional Commits) is used consistently across recent merged PRs (#956, #955, #951, #933, #932) but never documented.

## Expected behavior

Either:
- Expand the `## Development` section in `README.md` to include the dev-deps install command, the manual lint/typecheck/test commands, and the PR title convention, OR
- Add a `CONTRIBUTING.md` at the repo root and link it from the README's `## Development` section.

## Actual behavior

External contributors must read `pyproject.toml` (to discover the `dev` extras group), open `CLAUDE.md` (to find lint/test commands intended for Claude Code agents), and scan recent merged PRs (to infer the title format) before they can submit a clean PR.

## Environment

OS: macOS / Python: 3.12 / claude-agent-sdk: 0.2.82 (latest).

## Additional context

The information already exists across the repo; the fix is to consolidate it where contributors will find it. Happy to follow up with a PR adding `CONTRIBUTING.md` (or expanding the Development section) once the maintainer-preferred shape is confirmed.

Contributor guide

No contributing guide indexed for this repository

Research direction

Read README.md's ## Development section, then compare the contributor-facing details in pyproject.toml and CLAUDE.md. Consolidate the documented dev-dependency install, ruff, mypy, and pytest commands, plus the PR title convention, in the maintainer-preferred README.md or a new root CONTRIBUTING.md linked from the README. Done means an external contributor can find the complete workflow without consulting merged PRs.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.