Onboarding Devs Checklist

A chronological ramp-up from clone to first merged PR for new (or new-to-this-system) Python engineers - ordered before arrival, day 1, week 1, and ongoing.

How to Use This Checklist

Walk items in timeline order - earlier items unblock later ones.
The buddy owns ticking boxes with the new dev, not for them.
Hit required floor before day 2; ceiling items polish week 1.
Any item exceeding allotted time is a tooling or docs bug - fix for the next hire.

Phase 1 - Before They Arrive

Pre-file access: GitHub org, CI, cloud console (read-only staging), error tracker, docs wiki - access is the top day-one blocker.
Send README + onboarding doc link: Canonical doc in repo docs/onboarding.md with owner name.
Assign buddy: Named peer (not manager) with daily 15-minute check-in week 1.
Hardware or cloud dev environment: Laptop image or Codespaces template with Python 3.14 + uv documented.
First ticket ready: "Good first issue" scoped to 1-2 files with clear acceptance criteria.

Phase 2 - Day 1

Clone and bootstrap: git clone, uv sync, uv run pytest -q green per Environment Setup Checklist.
Run app locally: uv run uvicorn app.main:app --reload or make run - hit /health in browser or curl.
IDE extensions: Python, Ruff, mypy/pyright per team standard; format on save enabled.
Meet the team: Architecture 30-minute overview - monolith vs services, main data stores, deploy cadence.
Read codebase orientation: Codebase Orientation with buddy Q&A.

Phase 3 - Week 1

Trace one request end-to-end: Follow HTTP route to DB and back - draw personal diagram.
Read conventions: Conventions & Style Guide - ruff rules, commit format.
Shadow code review: Buddy walks one open PR - what reviewers expect (Code Review Guidelines).
First PR merged: Small real change (doc fix, test addition, typo in error message) - not a throwaway branch.
Log doc gaps: Every "I had to ask" becomes PR to onboarding doc same week.

Phase 4 - Ongoing (30-90 Days)

On-call shadow (if applicable): Pair on staging incident or simulated fire drill.
Own a small feature: Ticket sized 2-3 days with design note if needed.
Present learning: 5-minute demo or doc on one subsystem discovered.
Contribute to python-rules or ADR: Propose one rule clarification from confusion during onboarding.
Feedback retro: New hire + buddy + manager - what to add/remove from this checklist.

Applying the Checklist in Order

Phase 1-2 (1-10): Access and green local tests before expecting code contributions.
Phase 3 (11-15): First merged PR proves the pipeline works for this human, not just CI.
Phase 4 (16-20): Ownership and feedback close the loop for the next hire.

FAQs

Senior hire skip checklist?

Compress timeline but still run access, architecture, and conventions - seniors skip steps and become single points of failure.

Remote onboarding?

Same checklist - add timezone overlap hours and recorded architecture walkthrough.

Contractor vs FTE?

Contractors need same technical onboarding; shorten Phase 4 if short engagement.

Multiple repos?

Start with one "home" service repo; document cross-repo links in orientation doc.

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

Phase 1 - Before They Arrive

Pre-file access: GitHub org, CI, cloud console (read-only staging), error tracker, docs wiki - access is the top day-one blocker.

Send README + onboarding doc link: Canonical doc in repo docs/onboarding.md with owner name.

Assign buddy: Named peer (not manager) with daily 15-minute check-in week 1.

Hardware or cloud dev environment: Laptop image or Codespaces template with Python 3.14 + uv documented.

First ticket ready: "Good first issue" scoped to 1-2 files with clear acceptance criteria.

Phase 2 - Day 1

Clone and bootstrap: git clone, uv sync, uv run pytest -q green per Environment Setup Checklist.

Run app locally: uv run uvicorn app.main:app --reload or make run - hit /health in browser or curl.

IDE extensions: Python, Ruff, mypy/pyright per team standard; format on save enabled.

Meet the team: Architecture 30-minute overview - monolith vs services, main data stores, deploy cadence.

Read codebase orientation: Codebase Orientation with buddy Q&A.

Phase 3 - Week 1

Trace one request end-to-end: Follow HTTP route to DB and back - draw personal diagram.

Read conventions: Conventions & Style Guide - ruff rules, commit format.

Shadow code review: Buddy walks one open PR - what reviewers expect (Code Review Guidelines).

First PR merged: Small real change (doc fix, test addition, typo in error message) - not a throwaway branch.

Log doc gaps: Every "I had to ask" becomes PR to onboarding doc same week.

Phase 4 - Ongoing (30-90 Days)

On-call shadow (if applicable): Pair on staging incident or simulated fire drill.

Own a small feature: Ticket sized 2-3 days with design note if needed.

Present learning: 5-minute demo or doc on one subsystem discovered.

Contribute to python-rules or ADR: Propose one rule clarification from confusion during onboarding.

Feedback retro: New hire + buddy + manager - what to add/remove from this checklist.

FAQs

Senior hire skip checklist?

Compress timeline but still run access, architecture, and conventions - seniors skip steps and become single points of failure.

Remote onboarding?

Same checklist - add timezone overlap hours and recorded architecture walkthrough.

Contractor vs FTE?

Contractors need same technical onboarding; shorten Phase 4 if short engagement.

Multiple repos?

Start with one "home" service repo; document cross-repo links in orientation doc.

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

Onboarding Devs Checklist

Search Documentation

Onboarding Devs Checklist