developer-experience

Make Contributing Effortless

The single biggest factor in whether someone contributes to a project is how fast they can get a working development environment. If clone-to-passing-tests takes more than 60 seconds, every additional minute costs potential contributors. FastAPI, Pydantic, and httpx all converge on the same pattern: one prerequisite (uv), one command (uv sync --group dev), and every common task wrapped in a Makefile target. Invest in developer experience early -- every minute spent here pays back tenfold in contributor time saved.

One-Command Dev Setup

Target clone-to-running-tests in under 60 seconds. The modern standard uses uv with a committed lock file.

git clone https://github.com/org/my-package
cd my-package
uv sync --group dev     # Creates venv, installs package + all dev deps
uv run pytest           # Tests pass on first try

What makes this possible:

• Commit uv.lock to the repo for deterministic installs across machines
• Use PEP 735 dependency groups ([dependency-groups] in pyproject.toml) with a dev group
• Require no environment variables or config files to get started
• Rely on uv to install the correct Python version automatically

Step	Legacy (2020)	Modern (2026)
Install Python	pyenv install 3.x	uv handles it
Create virtualenv	python -m venv .venv	uv sync creates it
Activate	source .venv/bin/activate	Not needed (uv run)
Install deps	pip install -r requirements-dev.txt	uv sync --group dev
Install package	pip install -e .	Included in uv sync
Run tests	pytest	uv run pytest
Total commands	5-6	2 (clone + sync)

Task Automation with Makefile

Wrap every common operation in a Makefile target. Contributors type make test instead of remembering uv run pytest --cov --cov-report=term-missing -x -v. Use make help as the default target to make commands discoverable.

Required targets:

Target	Purpose
make dev	Install all dev dependencies + pre-commit hooks
make test	Run tests with coverage
make test-fast	Run tests without coverage (-x -q)
make lint	Run Ruff check + mypy
make format	Run Ruff format + fix
make docs	Serve docs locally with live reload
make build	Build sdist + wheel
make clean	Remove build artifacts and caches
make help	Show available targets (default goal)

Every CI step must map to a Makefile target. make lint locally runs the same checks as the lint CI job. If contributors cannot reproduce CI locally, they will push-and-pray.

Use justfile instead of Makefile only for team projects where contributors can install just. For open source libraries, Makefile is the safe default because it is pre-installed on macOS and Linux.

CONTRIBUTING.md

Include a CONTRIBUTING.md in the repository root. GitHub surfaces it automatically when users open issues and PRs. Structure it as a funnel from easiest to hardest contributions, following FastAPI's exemplary pattern.

Required sections (in order):

1. Welcome message -- thank potential contributors, set the tone
2. Ways to contribute -- list non-code contributions first (bug reports, docs, reviews)
3. Prerequisites -- document the single prerequisite (uv installation command)
4. Development setup -- exact shell commands, copy-pasteable
5. Running tests -- full suite, single file, pattern match, coverage
6. Code style -- tools used (Ruff, mypy), how to run them, pre-commit setup
7. Making changes -- branch naming, commit conventions, PR process
8. Documentation -- how to build and preview docs locally
9. Changelog entries -- Towncrier fragment format if applicable
10. Getting help -- link to GitHub Discussions

Rules for the contributing guide:

• Start with the easiest contributions (starring the repo, helping others on issues)
• Provide exact shell commands for every step -- never say "set up your environment"
• Explain the PR review process: who reviews, expected turnaround, merge strategy
• Test the commands in your contributing guide in CI to prevent documentation drift

Issue and PR Templates

Issue Templates

Place YAML form templates in .github/ISSUE_TEMPLATE/. Use structured forms instead of freeform markdown. Provide separate templates for bug reports and feature requests.

Bug report template must collect:

• Description, steps to reproduce (with code block placeholder), expected vs actual behavior
• Package version, Python version, operating system (as dropdown)
• Additional context (optional)

Feature request template must collect:

• Problem or motivation, proposed solution (with code block placeholder)
• Alternatives considered, willingness to submit a PR (as dropdown)

Disable blank issues in .github/ISSUE_TEMPLATE/config.yml with blank_issues_enabled: false. Redirect questions to GitHub Discussions via contact_links. Redirect security reports to the security advisory page.

PR Template

Place at .github/pull_request_template.md. Keep it short -- five to seven checklist items is the sweet spot. Templates with 20 checkboxes get ignored.

Required checklist items: tests added/updated, documentation updated, changelog entry added, CI passes, self-reviewed the diff. Include a type-of-change section (bug fix, feature, breaking change, docs, refactoring).

Community Health Files

CODE_OF_CONDUCT.md

Adopt the Contributor Covenant v2.1. Place it at CODE_OF_CONDUCT.md in the repository root. Designate specific enforcement contacts (not just "the project team"). Its absence signals that the project has not thought about community safety.

CODEOWNERS

Place at .github/CODEOWNERS. Map file patterns to responsible reviewers. This automatically requests reviews from the right people and, with branch protection, requires their approval before merging.

*               @org/maintainers
/docs/          @org/docs-team
pyproject.toml  @org/maintainers

.editorconfig

Ship an .editorconfig to enforce consistent whitespace regardless of individual editor settings. Set 4-space indent for Python, 2-space for YAML/JSON/TOML, tab for Makefile, and disable trailing whitespace trimming for Markdown.

SECURITY.md

See the security-supply-chain skill for the full SECURITY.md template, reporting channels, and response timeline.

README Best Practices

The README is the front page of the project. Most potential users decide within 30 seconds whether to keep reading.

Required sections (in order):

1. Badges -- PyPI version, Python versions, CI status, coverage (four badges, no more)
2. One-sentence elevator pitch -- what the package does and why it exists
3. Features -- 5-8 bullet points maximum
4. Installation -- pip install my-package
5. Quick start -- 5-15 lines of runnable code
6. Documentation link -- link to full docs
7. Contributing link -- link to CONTRIBUTING.md
8. License

Include in README	Keep out of README
Badges (4 max)	Full API reference
One-sentence pitch	Changelog
Feature list (5-8 items)	Detailed contributing instructions
Installation command	Every configuration option
Minimal quick-start example	CI matrix badges
Link to full docs	Animated GIFs (unless CLI tool)

First-Time Contributor Experience

Label issues as good first issue to signal approachable entry points. Effective good-first-issues are well-scoped (one file change), documented (pointers to relevant code), and non-blocking (not on the critical path).

Good "Good First Issue"	Bad "Good First Issue"
"Add type annotation to parse_config() in src/config.py"	"Refactor the plugin system"
"Add test for empty input to Client.fetch()"	"Fix the CI pipeline"
"Fix typo in API reference for validate()"	"Improve performance"

Structure the contribution path as a deliberate funnel: star/use the package, report a bug, fix a typo, add a test, implement a feature, review PRs, become a regular contributor. Each step should be explicitly documented and encouraged in CONTRIBUTING.md.

Review Checklist

When reviewing a project for developer experience and community health:

• Clone-to-passing-tests works in under 60 seconds with uv sync --group dev && uv run pytest
• uv.lock is committed to the repository for deterministic installs
• Makefile or justfile exists with help, dev, test, lint, format, docs, build, and clean targets
• Every CI step maps to a local Makefile/justfile target
• CONTRIBUTING.md exists with copy-pasteable setup commands, test instructions, and PR process
• .github/ISSUE_TEMPLATE/ contains bug report and feature request YAML form templates
• .github/ISSUE_TEMPLATE/config.yml disables blank issues and redirects questions to Discussions
• .github/pull_request_template.md exists with 5-7 checklist items
• CODE_OF_CONDUCT.md (Contributor Covenant v2.1) is present with designated enforcement contacts
• .editorconfig is present with correct settings for Python, YAML, Makefile, and Markdown
• README has badges (version, Python versions, CI, coverage), elevator pitch, install command, and quick-start example
• good first issue labels exist on well-scoped, documented issues
• CODEOWNERS file exists for multi-maintainer projects
• Contributing guide commands are tested in CI to prevent documentation drift