Skip to content

fix(review): gate.firstTimeContributorGrace is documented as softening blockers but is dead/inert #2266

Description

@JSONbored

Parent: #1936

Problem

.gittensory.yml.example documents gate.firstTimeContributorGrace: true as softening a would-be BLOCK to advisory/neutral for a genuine newcomer. The value is faithfully parsed, clamped, and threaded end-to-end through RepositorySettings into GateCheckPolicy at every call site — but evaluateGateCheckCore in src/rules/advisory.ts never reads policy.firstTimeContributorGrace (or its companions authorMergedPrCount/authorClosedUnmergedPrCount) anywhere in its body. A code comment confirms this was intentionally removed ("blocker findings must remain closure/rejection outcomes"), and an existing test (gate-check-policy.test.ts, "first-time-contributor grace compatibility") explicitly asserts a newcomer with grace=true still gets conclusion: "failure". The public-facing example config was simply never updated to reflect the removal.

This is not a guard weakening — the effective behavior is stricter than advertised, i.e. fails toward safe — but it's a real config-as-code correctness gap: a maintainer's mental model of their own gate's leniency toward newcomers is wrong.

Failure scenario: a repo owner reads the example file and sets gate.firstTimeContributorGrace: true believing it will give first-time contributors a grace period before a blocker auto-closes their PR. Nothing changes — a first-time contributor with a real blocker is still one-shot closed exactly as a repeat contributor would be, with no warning that the setting is inert.

Requirements

  • The documented behavior of every config-as-code field must match its actual runtime effect — or the field must be removed/marked reserved with a runtime warning.

Deliverables

  • Remove/update the .gittensory.yml.example entry (and corresponding descriptions in types.ts/OpenAPI/settings-preview) to state the flag is currently inert/reserved, since the design comment indicates the removal was deliberate.
  • Consider emitting a one-time warning in manifest.warnings when a repo sets firstTimeContributorGrace to a non-default value, so maintainers relying on it get a visible signal rather than silent inertness.

Acceptance criteria

  • The example config and public docs no longer claim firstTimeContributorGrace softens a blocker outcome.
  • A repo that sets this field gets a visible signal (doc note and/or runtime warning) that it currently has no effect.

Expected outcome

A maintainer configuring gate leniency for newcomers can trust that what they read in the docs matches what actually happens at gate time.

Metadata

Metadata

Assignees

Labels

maintainer-onlyOwner-only work — yields no Gittensor points.

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions