Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

contributing(docs): clarify draft PR and bot claims (#2317)

Karl Von Richterb8d7b4280844
diff --git a/AGENTS.md b/AGENTS.md
index dbdea8822e..fa334ea2de 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 `<summary> (#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 a077bb7460..a5ab22889c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -258,6 +258,9 @@ and a fresh CI run:
open a **draft** PR titled `<summary> (#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