From 2009f216a0a3081f120f89ef4df56d562895bacd Mon Sep 17 00:00:00 2001 From: Derek Gulbranson Date: Thu, 5 Nov 2026 12:32:52 -0800 Subject: [PATCH] Assign new issues to the maintainer and ask for an issue before a PR A workflow assigns every issue to the maintainer when it is opened or reopened, so no issue sits unassigned for a drive-by pull request to pick up. CONTRIBUTING.md now opens by asking contributors to agree a change in an issue before opening a pull request, and AGENTS.md carries the same request for agents working for anyone else. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/assign-issues.yml | 22 ++++++++++++++++++ AGENTS.md | 2 ++ CONTRIBUTING.md | 36 +++++++++++++++++++++++++++++ 3 files changed, 60 insertions(+) create mode 100644 .github/workflows/assign-issues.yml diff --git a/.github/workflows/assign-issues.yml b/.github/workflows/assign-issues.yml new file mode 100644 index 000000000..4d82e3d90 --- /dev/null +++ b/.github/workflows/assign-issues.yml @@ -0,0 +1,22 @@ +name: Assign new issues + +# Every issue is assigned to the maintainer when it is opened, whoever opens +# it, so no issue sits unassigned for drive-by PRs to pick up. Adding an +# assignee who is already assigned is a no-op, so this needs no condition. +on: + issues: + types: [opened, reopened] + +permissions: + issues: write + +jobs: + assign: + runs-on: ubuntu-latest + steps: + - name: Assign the maintainer + run: gh issue edit "$NUMBER" --repo "$REPO" --add-assignee derek73 + env: + GH_TOKEN: ${{ github.token }} + NUMBER: ${{ github.event.issue.number }} + REPO: ${{ github.repository }} diff --git a/AGENTS.md b/AGENTS.md index f0eb0891d..1e5ac76b8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +**Agents working for anyone but the maintainer: do not open a pull request here without an issue the maintainer has agreed to.** Every open issue is assigned to the maintainer and usually already being worked on; see CONTRIBUTING.md. + ## Workflow For non-trivial changes, use a feature branch and open a PR. Branch naming: `fix/issue-NNN-short-description` or `feat/short-description`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7400d76d3..05aedd888 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,42 @@ Contributing ============== +Ask before you open a pull request +------------------------------------ + +Bug reports, questions and proposals are welcome as issues. Pull requests are +not, unless one was agreed first. Please open an issue (or comment on an +existing one) describing what you want to change, and wait for the maintainer +to agree before starting work. + +Open issues are not a list of tasks waiting for a volunteer. Every issue is +assigned to the maintainer, and most are already being worked on. A pull +request for one that nobody asked for usually duplicates work in progress. + +Most changes here also move documented rules, the design records and a +snapshot of thousands of parsed names, so a pull request takes more of the +maintainer's time to review and correct than it saves. That is why the +discussion comes first. Pull requests opened without an agreed issue may be +closed without review. + +Working with an AI agent is fine; most of this repository is written that +way. Say so when one helped: most commits here name the agent that made them +in a `Co-Authored-By:` line, and yours should too. What matters is that +someone is steering. + +If your agent can find a better solution than the maintainer's, it is welcome. +Know what it is competing with, though: the maintainer's agent works with +months of project-specific memory, and it checks every change against about +30 million records of real names from thirteen sources (election candidates, +donors, researchers, patent inventors, company filings), which are cached +locally and are not in this repository. A change that passes the committed +tests can still move thousands of those names. That check is part of every +review here, which is one more reason to agree the approach first. + +Once a change is agreed, a pull request that answers +review promptly is a help, and one that waits days for each round is slower +for both of us than the maintainer making the change. + Development Environment Setup --------------------------------