docs(contributing): define the AI-assisted starter-issue lane
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
## Problem
`CONTRIBUTING.md` routes new contributors to `good first issue`, but the current queue does not consistently represent ready, low-risk work.
Current-state audit:
- #5745 is seven of eight acceptance criteria complete. Its only remaining gate is a trusted, secret-bearing GitHub Actions dispatch that an ordinary contributor must not perform.
- #6639 is blocked until an upstream release provides an ownership-safe gateway stop/reap contract and supported macOS hardware evidence proves the fallback can be removed.
- #6042 belongs to the NVIDIA QA lane. It may remain useful work, but it should not be the non-QA community queue's operating baseline.
- #8283 describes removal of `rebuild-finalization.ts`, but that file and its test are already absent from current `main`; the issue needs completion/closure review, not a new contributor.
This makes the label query look more actionable than it is and encourages contributors to spend time rediscovering hidden blockers.
The repository also does not state concise expectations for AI-assisted pull requests or unsolicited AI-generated review comments. Maintainers need a public rule that encourages useful assistance without accepting broad generated changes or large review dumps as evidence of quality.
## Goal
Maintain a small, truthful non-QA starter queue and document contribution-quality expectations for AI-assisted work.
## Proposed starter-issue contract
An issue may carry `good first issue` only while all of these conditions hold:
- Maintainers have accepted the work and no product, architecture, security, or ownership decision remains.
- The issue is actionable on current `main`.
- No assignee or open pull request already owns it.
- One independently useful outcome fits in one pull request.
- The blast radius is small and does not include credentials, permissions, security controls, release authority, policy changes, live hardware, or secret-bearing validation.
- The body names the current code or documentation owner, observable acceptance criteria, the smallest stable verification command, and any platform prerequisite.
- No external dependency, private service, or maintainer-only action is required to prove completion.
Remove the label when a pull request opens, the issue becomes blocked, current `main` satisfies it, or the acceptance contract grows beyond this boundary.
The non-QA community queue should maintain five ready issues. Five is a queue-health target, not permission to invent low-value work. When fewer than five real candidates exist, the query should truthfully show fewer than five.
## Proposed AI-assisted contribution guidance
Add concise guidance to `CONTRIBUTING.md`:
- Start from an accepted issue and keep one pull request to one outcome.
- Read the current implementation and tests before editing; generated code does not replace understanding or validation.
- The author owns every submitted line, test result, and claim, regardless of the tool used.
- Do not open placeholder pull requests, split one fix across several trivial pull requests, or add speculative helpers and abstractions.
- Keep review comments to current, actionable defects with checked-in evidence. Group symptoms by root cause.
- Do not post exhaustive AI-generated reviews, repeated restatements, style-only dumps, or findings unrelated to the pull request's accepted scope.
- Maintainers may close manifestly low-effort or duplicative work and direct the contributor to a scoped starter issue.
Do not add automatic closing or scoring in the first change. The initial contract should be human-readable, reviewable, and applied consistently before automation is considered.
## Initial queue maintenance
- Remove `good first issue` from #5745 and add `needs: unblock` until the trusted hosted-mode dispatch is completed.
- Remove `good first issue` from #6639 and add `needs: unblock` until its upstream and hardware conditions are satisfied.
- Keep #6042 in the QA operating lane; do not count it toward the five-item non-QA target.
- Review #8283 for closure against current `main` rather than routing a contributor to it.
- Audit new candidates against the contract before labeling them. Record the code owner, stable local check, and absence of an active pull request in the issue.
## Acceptance criteria
- [ ] `CONTRIBUTING.md` contains the starter-issue contract and AI-assisted contribution guidance without naming a specific AI vendor or tool.
- [ ] Every open non-QA `good first issue` is actionable on current `main` and satisfies the contract above.
- [ ] The queue contains up to five real ready items; no placeholder issue is created merely to reach five.
- [ ] A maintainer-owned check cadence is recorded for removing stale, blocked, assigned, or PR-owned labels.
- [ ] The existing label query remains the single contributor entry point.
- [ ] No automatic close, contributor score, or new label taxonomy is introduced.
## Non-goals
- Changing the NVIDIA QA operating process.
- Automatically rejecting pull requests based on author, tool, size, or writing style.
- Requiring disclosure of a particular coding assistant.
- Treating all large or AI-assisted contributions as low quality.
Contributor guide
Research direction
Start with CONTRIBUTING.md and the existing good first issue label query, then review issues #5745, #6639, #6042, and #8283 against the proposed contract on current main. Update the contribution guidance and perform the stated queue maintenance; done means the acceptance criteria are met without introducing automation, scoring, or new labels.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, typescript
- Domain
- developer-experience, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100