From b8d7b4280844228cb3e335217c37ecff77dc8b8a Mon Sep 17 00:00:00 2001 From: Karl Von Richter Date: Sun, 18 Oct 2026 16:11:29 +1000 Subject: [PATCH] contributing(docs): clarify draft PR and bot claims (#2317) Document the maintainer-confirmed workflow: open a draft PR to establish ownership, then comment /claim to mark the issue as taken. Align AGENTS.md and CONTRIBUTING.md and distinguish the existing takeover policy from the bot's automatic cleanup deadlines. Signed-off-by: Karl Von Richter --- AGENTS.md | 6 +++++- CONTRIBUTING.md | 12 ++++++++---- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dbdea882..fa334ea2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -132,9 +132,13 @@ People trust SolidCraft with their designs; a crash loses their work. **This out - Before working on issue #N, check nobody has it: `gh pr list -R bherbruck/solidcraft --state open --search "#N"`. - If none, branch from the latest `origin/main`, `git commit --allow-empty -m "claim: #N"`, push, and open a **draft** PR titled ` (#N)` right away. **The lowest-numbered open PR for an - issue wins**; if yours lost, close it. Don't claim by commenting or by editing files. + issue wins**; if yours lost, close it. A comment or file edit alone does not replace the draft PR. +- After opening the draft PR, comment `/claim` on the issue so the bot records the claimant and + adds the `in progress` label. **Do both:** the draft PR establishes ownership and `/claim` marks + the issue as taken. Reference `#N` in the PR so the bot can find it. - Push work in progress at least daily. A draft with no pushes for 72 hours may be taken over: comment on it first, then open your own claim (you may start from its branch). + This takeover policy is separate from the bot's automatic cleanup deadlines in CONTRIBUTING.md. - On a shared build machine, check the load before a big build (`cut -d' ' -f1 /proc/loadavg`) and wait while it is over 24; build with `nice`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a077bb74..a5ab2288 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -258,6 +258,9 @@ and a fresh CI run: open a **draft** PR titled ` (#N)`, e.g. `Fillet: variable radius along a chain (#123)`. - **The lowest-numbered open PR for an issue wins.** If yours lost, close it (or offer to help on the other one). + - Then comment `/claim` on the issue so the bot records the claimant and adds the `in progress` + label. **Do both:** the draft PR establishes ownership and `/claim` marks the issue as taken. + Reference `#N` in the PR so the bot can find it; a comment alone does not replace the draft PR. - Push work in progress at least daily. A draft with no pushes for 72 hours may be taken over: comment on it first, then open your own claim. - Mark the PR ready for review when it is done. @@ -267,10 +270,11 @@ and a fresh CI run: 4. Reference the issue (`Fixes #12`). In the PR, say what you tested and how. For geometry work, include the measured numbers (and the expected ones). -Comment `/claim` on an issue to take it: you are assigned, it gets the `in progress` label, and -the bot replies with the deadline. Open a draft PR referencing the issue within 72 hours, or the -claim lapses and the issue is freed again; a claim with a PR is freed after 14 days without -pushes. `/unclaim` releases it early (only you or a maintainer can). Issues a maintainer has +The `/claim` bot assigns you, adds the `in progress` label, and replies with its automatic cleanup +deadline. It frees a claim with no linked PR after 72 hours, or a claim with a PR after 14 days +without pushes. These automatic cleanup deadlines are separate from the daily progress and +72-hour takeover policy above; follow the draft PR then `/claim` sequence before starting work. +`/unclaim` releases the bot claim early (only you or a maintainer can). Issues a maintainer has taken are never freed automatically. Help reviewers see what the words mean. For observable CAD, UI or model behavior, please