diff --git a/docs/getting-started/RUNBOOK_ASKING_FOR_REVIEW.md b/docs/getting-started/RUNBOOK_ASKING_FOR_REVIEW.md new file mode 100644 index 00000000..98830128 --- /dev/null +++ b/docs/getting-started/RUNBOOK_ASKING_FOR_REVIEW.md @@ -0,0 +1,12 @@ +# Contributor Runbook: Asking for Review + +1. Before requesting review: + - Run `python3 -m pytest -q` — all tests must pass. + - Run `python scripts/check_doc_links.py` — no broken links. + - Run `python scripts/safety/check_claims.py` — no overclaiming language. +2. Request review from the relevant maintainer. +3. In your review request, note: + - What the change does + - What testing you've done + - Any areas you're unsure about +4. Respond to review comments promptly. diff --git a/docs/getting-started/RUNBOOK_BLOCKED_WORK.md b/docs/getting-started/RUNBOOK_BLOCKED_WORK.md new file mode 100644 index 00000000..7f7474b1 --- /dev/null +++ b/docs/getting-started/RUNBOOK_BLOCKED_WORK.md @@ -0,0 +1,9 @@ +# Contributor Runbook: Blocked Work + +1. Document what's blocking you in the issue or PR comments. +2. Tag the relevant maintainer or area expert. +3. Suggest a path forward if you have one. +4. If the block cannot be resolved in 48 hours, consider: + - Picking up a different issue + - Reducing the scope of your current change + - Asking in a project discussion diff --git a/docs/getting-started/RUNBOOK_HANDLING_REVIEW.md b/docs/getting-started/RUNBOOK_HANDLING_REVIEW.md new file mode 100644 index 00000000..77781da3 --- /dev/null +++ b/docs/getting-started/RUNBOOK_HANDLING_REVIEW.md @@ -0,0 +1,11 @@ +# Contributor Runbook: Handling Review Feedback + +1. Read all feedback before responding. +2. Separate into: + - **Required changes** — must be addressed before merge. + - **Suggestions** — optional improvements. + - **Questions** — need clarification. +3. Make required changes, push to the same branch. +4. Reply to each comment indicating what you changed. +5. If you disagree with feedback, explain your reasoning respectfully. +6. After addressing all feedback, re-request review. diff --git a/docs/getting-started/RUNBOOK_PAUSING_WORK.md b/docs/getting-started/RUNBOOK_PAUSING_WORK.md new file mode 100644 index 00000000..b0eb4642 --- /dev/null +++ b/docs/getting-started/RUNBOOK_PAUSING_WORK.md @@ -0,0 +1,7 @@ +# Contributor Runbook: Pausing Work + +1. If you have uncommitted changes, stash or commit them on a branch. +2. Comment on the issue that you're pausing and why. +3. If you expect to resume within a week, leave the branch. +4. If you won't resume, unassign yourself and mark the issue as available. +5. Document any context that will help the next person continue. diff --git a/docs/getting-started/RUNBOOK_PICKING_UP_ISSUE.md b/docs/getting-started/RUNBOOK_PICKING_UP_ISSUE.md new file mode 100644 index 00000000..8c8a1986 --- /dev/null +++ b/docs/getting-started/RUNBOOK_PICKING_UP_ISSUE.md @@ -0,0 +1,8 @@ +# Contributor Runbook: Picking Up an Issue + +1. Find an open issue labelled `good-first-issue` or `help-wanted`. +2. Comment on the issue that you're working on it. +3. Ask clarifying questions if the scope is unclear. +4. Create a branch from `main`. +5. Make your change, add tests, verify nothing is broken. +6. Create a PR that references the issue number. diff --git a/tests/test_contributor_runbooks.py b/tests/test_contributor_runbooks.py new file mode 100644 index 00000000..b4b2c961 --- /dev/null +++ b/tests/test_contributor_runbooks.py @@ -0,0 +1,21 @@ +"""Tests for contributor runbooks.""" +from pathlib import Path + +RUNBOOKS = [ + "RUNBOOK_PICKING_UP_ISSUE.md", + "RUNBOOK_BLOCKED_WORK.md", + "RUNBOOK_PAUSING_WORK.md", + "RUNBOOK_ASKING_FOR_REVIEW.md", + "RUNBOOK_HANDLING_REVIEW.md", +] + + +def test_all_exist(): + for r in RUNBOOKS: + assert Path(f"docs/getting-started/{r}").exists(), f"Missing: {r}" + + +def test_each_has_content(): + for r in RUNBOOKS: + text = Path(f"docs/getting-started/{r}").read_text() + assert len(text) > 50, f"{r} is too short"