Skip to content

docs(contributing): say that a claim is a courtesy, not a lock - #630

Merged
cevheri merged 1 commit into
mainfrom
docs/claim-is-not-a-lock
Sep 7, 2026
Merged

docs(contributing): say that a claim is a courtesy, not a lock#630
cevheri merged 1 commit into
mainfrom
docs/claim-is-not-a-lock

Conversation

@cevheri

@cevheri cevheri commented Sep 7, 2026

Copy link
Copy Markdown
Member

Two contributors reached #621 ten minutes apart. It was claimed at 13:04 UTC, and #627 arrived at 13:16 with a commit dated 13:14. A change of that shape, two providers plus both provider docs plus eight tests, is not written in ten minutes, so the work predated the claim, and its author could not have seen the claim either: GitHub sends no notification for a comment on an issue you already have open.

The claim bullet in CONTRIBUTING.md read as an exclusive hold and said nothing about that case, which left the outcome looking like a judgement of one of the two people. It is not one. This adds the rule the collision was actually decided by, so the next pair of contributors can read it before it happens to them rather than after:

  • the clock rather than the claim, since work already in flight is not queue-jumping
  • delivered work reviewed on its merits
  • nobody asked to write the same change twice
  • the nearest open issue, plus review credit, for whoever does not land it

Worth noting what this exposed: the sentence contributors actually read first, "Comment to claim it before you start", is not in a template at all. .github/ISSUE_TEMPLATE/ holds only bug_report.md and feature_request.md, and neither mentions claiming; the sentence is hand-copied into the body of each curated issue, where nothing in the repository can guard it. Making CONTRIBUTING.md the single authority does not change the rule, but it is the first time the rule lives somewhere checkable. Repointing those issue footers at this section is a separate change.

Deliberately not in this PR

No test. The paragraph carries no cross-file invariant to guard, and pinning its prose verbatim would fail on the next honest edit while proving nothing. tests/unit/contributors-doc.test.ts guards what is guardable here, the ladder's two halves and the absence of a count, and it still passes: 9 tests, and the new bullet is a list item rather than a rung heading, so rung extraction is untouched.

The staleness window is unchanged. "A claimed issue with no activity for two weeks is open again" stays as it is. Shortening it, or distinguishing a claim with a branch behind it from one without, is a policy decision rather than a wording fix, and it belongs in its own change.

Verification

bun run format, bun run lint, bun run readme:check and bun run security:check pass, and bun test tests/unit/contributors-doc.test.ts is 9 pass / 0 fail.

Two contributors reached #621 ten minutes apart: it was claimed at 13:04 UTC
and #627 arrived at 13:16 with a commit dated 13:14. The author of the pull
request could not have seen the claim, because GitHub sends no notification
for a comment on an issue you already have open.

The claim bullet read as an exclusive hold and said nothing about that case,
so it left the outcome looking like a judgement of one of the two people. It
is not one. State the rule the collision was actually decided by: the clock
rather than the claim, delivered work reviewed on its merits, nobody asked to
write the same change twice, and the nearest open issue plus review credit for
whoever does not land it.

No test. The paragraph carries no cross-file invariant to guard, and pinning
its prose verbatim would fail on the next honest edit while proving nothing.
The two-week staleness window above it is unchanged and still open to review.
@codecov

codecov Bot commented Sep 7, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@sonarqubecloud

sonarqubecloud Bot commented Sep 7, 2026

Copy link
Copy Markdown

@cevheri
cevheri merged commit d6a2cd4 into main Sep 7, 2026
33 of 34 checks passed
@cevheri
cevheri deleted the docs/claim-is-not-a-lock branch September 7, 2026 15:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant