Skip to content

Commit a4e2c91

Browse files
johntmyersjohntmyers
authored
chore: add vouch system for first-time contributors (#375)
chore: add vouch system for first-time contributors
1 parent 8235fe9 commit a4e2c91

File tree

8 files changed

+157
-0
lines changed

8 files changed

+157
-0
lines changed

‎.github/CODEOWNERS‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,6 @@
44
# Agent infrastructure — tighter review
55
.agents/ @NVIDIA/openshell-codeowners
66
AGENTS.md @NVIDIA/openshell-codeowners
7+
8+
# Vouch list — maintainers only (bot commits bypass, but manual edits need review)
9+
.github/VOUCHED.td @NVIDIA/openshell-codeowners

‎.github/DISCUSSION_TEMPLATE/vouch-request.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
title: "Vouch request: [your GitHub username]"
2+
labels: []
3+
body:
4+
- type: markdown
5+
attributes:
6+
value: |
7+
## Vouch Request
8+
9+
OpenShell uses a vouch system for first-time contributors. Fill out this
10+
form to request approval. A maintainer will review and comment `/vouch`
11+
if approved.
12+
13+
**Write in your own words.** Do not have an AI generate this request.
14+
Requests that read like LLM output will be denied.
15+
16+
- type: textarea
17+
id: what
18+
attributes:
19+
label: What do you want to work on?
20+
description: >
21+
Describe the change you want to make. Link to an existing issue if
22+
there is one.
23+
placeholder: "I want to fix #123 which causes sandbox timeouts when..."
24+
validations:
25+
required: true
26+
27+
- type: textarea
28+
id: why
29+
attributes:
30+
label: Why this change?
31+
description: >
32+
Explain your motivation and why this matters. Keep it concise.
33+
placeholder: "This bug affects anyone running sandboxes on ARM64 because..."
34+
validations:
35+
required: true
36+
37+
- type: checkboxes
38+
id: checklist
39+
attributes:
40+
label: Checklist
41+
options:
42+
- label: I wrote this request myself (not AI-generated)
43+
required: true
44+
- label: I have read [CONTRIBUTING.md](https://github.com/NVIDIA/OpenShell/blob/main/CONTRIBUTING.md)
45+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
blank_issues_enabled: false
22
contact_links:
3+
- name: First-time contributor? Get vouched first
4+
url: https://github.com/NVIDIA/OpenShell/discussions/new?category=vouch-request
5+
about: >
6+
First-time contributors must be vouched before submitting PRs. Open a
7+
Vouch Request discussion describing what you want to work on. A
8+
maintainer will approve you with /vouch.
39
- name: Have a question?
410
url: https://github.com/NVIDIA/OpenShell/blob/main/CONTRIBUTING.md#agent-skills-for-contributors
511
about: >

‎.github/VOUCHED.td‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Vouched Contributors
2+
#
3+
# Users listed here have been approved to submit pull requests.
4+
# Org members and collaborators with write access bypass this check automatically.
5+
#
6+
# Maintainers vouch new contributors by commenting "/vouch" on their
7+
# Vouch Request discussion. The vouch-command workflow updates this file.
8+
#
9+
# Format: one GitHub username per line, no @ prefix. Sorted alphabetically.
10+
# Prefix with - to denounce. See https://github.com/mitchellh/vouch for details.

‎.github/workflows/vouch-check.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: Vouch Check
2+
3+
on:
4+
pull_request_target:
5+
types: [opened, reopened]
6+
7+
permissions:
8+
contents: read
9+
pull-requests: write
10+
11+
jobs:
12+
vouch-gate:
13+
if: github.repository_owner == 'NVIDIA'
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: mitchellh/vouch/action/check-pr@v1
17+
with:
18+
pr-number: ${{ github.event.pull_request.number }}
19+
auto-close: true
20+
env:
21+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/vouch-command.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Vouch Command
2+
3+
on:
4+
discussion_comment:
5+
types: [created]
6+
7+
concurrency:
8+
group: vouch-manage
9+
cancel-in-progress: false
10+
11+
permissions:
12+
contents: write
13+
discussions: write
14+
15+
jobs:
16+
process-vouch:
17+
if: github.repository_owner == 'NVIDIA'
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@v4
21+
22+
- uses: mitchellh/vouch/action/manage-by-discussion@v1
23+
with:
24+
discussion-number: ${{ github.event.discussion.number }}
25+
comment-node-id: ${{ github.event.comment.node_id }}
26+
vouch-keyword: "/vouch"
27+
denounce-keyword: "/denounce"
28+
unvouch-keyword: "/unvouch"
29+
env:
30+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎AGENTS.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,19 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
4545
| `.agents/agents/` | Agent personas | Sub-agent definitions (e.g., reviewer, doc writer) |
4646
| `architecture/` | Architecture docs | Design decisions and component documentation |
4747

48+
## Vouch System
49+
50+
- First-time external contributors must be vouched before their PRs are accepted. The `vouch-check` workflow auto-closes PRs from unvouched users.
51+
- Org members and collaborators bypass the vouch gate automatically.
52+
- Maintainers vouch users by commenting `/vouch` on a Vouch Request discussion. The `vouch-command` workflow appends the username to `.github/VOUCHED.td`.
53+
- Skills that create PRs (`create-github-pr`, `build-from-issue`) should note this requirement when operating on behalf of external contributors.
54+
4855
## Issue and PR Conventions
4956

5057
- **Bug reports** must include an agent diagnostic section — proof that the reporter's agent investigated the issue before filing. See the issue template.
5158
- **Feature requests** must include a design proposal, not just a "please build this" request. See the issue template.
5259
- **PRs** must follow the PR template structure: Summary, Related Issue, Changes, Testing, Checklist.
60+
- **PRs from unvouched external contributors** are automatically closed. See the Vouch System section above.
5361
- **Security vulnerabilities** must NOT be filed as GitHub issues. Follow [SECURITY.md](SECURITY.md).
5462
- Skills that create issues or PRs (`create-github-issue`, `create-github-pr`, `build-from-issue`) should produce output conforming to these templates.
5563

‎CONTRIBUTING.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,40 @@
22

33
OpenShell is built agent-first. We design systems and use agents to implement them. Your agent is your first collaborator — point it at this repo before opening issues, asking questions, or submitting code.
44

5+
## The Critical Rule
6+
7+
**You must understand your code.** Using AI agents to write code is not just acceptable, it's how this project works. But you must be able to explain what your changes do and how they interact with the rest of the system. If you can't, don't submit it.
8+
9+
Submitting agent-generated code without understanding it — regardless of how clean it looks — wastes maintainer time and will result in your PR being closed. Repeat offenders will be blocked from the project.
10+
11+
## AI Usage
12+
13+
OpenShell is agent-first, not agent-only. The distinction matters:
14+
15+
- **Do** use agents to explore the codebase, run diagnostics, generate code, and iterate on implementations.
16+
- **Do** use the skills in `.agents/skills/` — they exist to make your agent effective.
17+
- **Do** interrogate your agent until you understand every edge case and interaction in your changes.
18+
- **Don't** submit code you can't explain without your agent open.
19+
- **Don't** use agents as a substitute for understanding the system. Read the architecture docs.
20+
21+
## First-Time Contributors
22+
23+
We use a vouch system. This exists because AI makes it trivial to generate plausible-looking but low-quality contributions, and we can no longer trust by default.
24+
25+
1. Open a [Vouch Request](https://github.com/NVIDIA/OpenShell/discussions/new?category=vouch-request) discussion.
26+
2. Describe what you want to change and why.
27+
3. Write in your own words. AI-generated vouch requests will be denied.
28+
4. A maintainer will comment `/vouch` if approved.
29+
5. Once vouched, you can submit pull requests.
30+
31+
**If you are not vouched, any pull request you open will be automatically closed.** Org members and collaborators with push access bypass this check.
32+
33+
### Finding Work
34+
35+
Issues labeled [`good-first-issue`](https://github.com/NVIDIA/OpenShell/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue) are scoped, well-documented, and friendly to new contributors. Start there. If you need guidance, comment on the issue.
36+
37+
All open issues are actionable — if it's in the issue tracker, it's ready to be worked on.
38+
539
## Before You Open an Issue
640

741
This project ships with [agent skills](#agent-skills-for-contributors) that can diagnose problems, explore the codebase, generate policies, and walk you through common workflows. Before filing an issue:

0 commit comments

Comments
 (0)