Skip to content

Add CONTRIBUTORS.md: issues-only policy (share prompts, not PRs) #1517

Closed
#1604
Closed
Add CONTRIBUTORS.md: issues-only policy (share prompts, not PRs)#1517
#1604
Assignees
cliffhall
Labels
v2Issues and PRs for v2
Milestone
v2.0.0

Description

@cliffhall
cliffhall
opened on Jun 24, 2026

Summary

Add a new CONTRIBUTORS.md at the repository root that documents our contribution policy going forward: we accept issues, not pull requests. Design and implementation are done by the maintainers. When a contributor has already built a fix or feature locally, they should share the prompt they used to produce it — not the source code.

Why

The Inspector v2 is developed with an AI-assisted, prompt-driven workflow with a consistent architecture, design system, and testing gates (see AGENTS.md). Accepting raw source PRs creates friction: they must be reverse-engineered to fit our component/theme conventions, coverage gates, and review process. Capturing the intent (a well-formed issue) or the prompt that generated a local change lets us reproduce the work within our own pipeline and standards.

Requirements

Create CONTRIBUTORS.md (root) covering:

  • Policy statement: We accept issues only. Pull requests from external contributors will not be merged. The maintainers handle design and implementation.
  • How to contribute a bug report or feature request: open a well-scoped issue against the version it targets. Reference the labeling-by-version convention from AGENTS.md.
    • Include a table mapping each active version to its base branch and version label (folded in from docs: complete CONTRIBUTORS.md with the version-board/label table (satisfies #1517 req #2) #1595). Shipped as a version → base branch → label table:
      • v1/main → label v1 — legacy Inspector, security fixes only
      • main → label v2 — where all current work happens
    • Add a short "Label by version" note mirroring AGENTS.md (new issues/PRs must carry the label matching the target branch).
  • If you've already fixed it locally: don't send a diff/PR. Instead, share the prompt(s) you used to generate the change, plus a description of the behavior before/after and how you verified it. We'll reproduce it through our own workflow.
  • What makes a good issue / prompt submission: clear reproduction or use case, expected vs. actual behavior, affected client (Web / TUI / CLI), and the exact prompt text if applicable.
  • Rationale: briefly explain the prompt-driven workflow so the policy reads as intentional, not dismissive.
  • Cross-reference: link from AGENTS.md to CONTRIBUTORS.md so it's discoverable (new ## Contributing section).
  • GitHub PR template redirecting would-be external PR authors to the policy (listed as an optional follow-up in the original notes; shipped in this PR).
  • "Want to work on the Inspector with us?" section — the issues-only rule applies to unsolicited patches, not to people who want to contribute properly. Points at #inspector-dev on the MCP Contributor Discord and the community calls, and names supervised, scoped work as the path toward maintainership. (Review feedback on docs: add CONTRIBUTORS.md issues-only policy (closes #1517) #1604.)

Deviations from the original spec

Three requirements above were deliberately changed during review and after alignment with the go-live runbook (#1804). Recorded here so the shipped doc doesn't read as drift:

Notes

  • Keep the tone welcoming — contributors are valued; the policy is about channeling their input into a form we can act on efficiently.

Consolidated: #1595 (completeness of the version→board/label table in requirement #2) has been folded into this issue and closed.

Status

✅ Shipped in #1604 (merged to v2/main as b3be65b). Follow-up doc sweep tracked in #1813.

Activity

  1. cliffhall
    self-assigned this
    on Jun 24, 2026
  2. cliffhall
    added
    v2Issues and PRs for v2
    on Jun 24, 2026
  3. cliffhall
    added 2 commits that reference this issue on Jun 27, 2026

    docs: add PR template redirecting external authors to issues-only pol…

    cc1e707

    docs: drop version-board details from CONTRIBUTORS.md (#1517)

    f7a746c
  4. cliffhall
    linked a pull request that will close this issuedocs: add CONTRIBUTORS.md issues-only policy (#1517) #1537on Jun 30, 2026

  5. cliffhall commented on Jul 1, 2026

    @cliffhall
    cliffhall
    on Jul 1, 2026
    MemberAuthor

    Audit — PR #1537

    Audited chore/1517-contributors-md (origin/v2/main...HEAD). This is a documentation-only change (3 files: CONTRIBUTORS.md new, .github/pull_request_template.md new, AGENTS.md +7 lines). No runtime surface, no UI, no coverage surface — so no functional smoke test, Playwright screenshot, or coverage run is applicable. Verification here is link/anchor/cross-reference correctness plus consistency with the issue's checklist.

    Link / anchor / cross-reference verification

    Check Result
    CONTRIBUTORS.md exists at root with issues-only policy ✅ present (71 lines)
    Internal anchor #what-makes-a-good-issue-or-prompt-submission ✅ resolves (heading slug matches)
    CONTRIBUTORS.md → [AGENTS.md](./AGENTS.md) ✅ target exists at root
    AGENTS.md → [CONTRIBUTORS.md](./CONTRIBUTORS.md) ✅ target exists at root
    PR template absolute URL …/blob/v2/main/CONTRIBUTORS.md ✅ resolves post-merge (forward ref)
    No root README.md exists → AGENTS.md used as cross-ref point ✅ correct (issue allows "README.md and/or AGENTS.md")

    Findings

    1. (Substantive) Issue requirement #2 not fully met; PR body over-claims.
    Requirement #2 asks the "how to report a bug / request a feature" section to "open a well-scoped issue on the appropriate version board (v2 → v2 board / v2/main)" and "reference the labeling-by-version convention from AGENTS.md (v1 / v1.5 / v2)." The committed CONTRIBUTORS.md section is generic — it contains no version-board mapping, no base-branch/label guidance, and no reference to the "Label by version" convention (verified: 0 occurrences of board, label, v1.5, Label by version, and 0 table rows in the file). The PR description, however, claims the doc includes "a table mapping v2 / v1.5 / v1 to their boards, base branches, and labels (cross-referencing the 'Label by version' convention in AGENTS.md)" — that content is not present in the file. Not a blocker for the policy's intent, but the requirement checkbox is only partially satisfied and the PR body is inaccurate on this point.

    2. (Nit) PR template visible link uses a fragile relative path.
    The HTML-comment block correctly uses the absolute URL. The visible blockquote uses [CONTRIBUTORS.md](../blob/v2/main/CONTRIBUTORS.md) — an unusual ../blob/… relative path that will not resolve cleanly in most render contexts. Prefer the same absolute URL (or a root-relative /modelcontextprotocol/inspector/blob/v2/main/CONTRIBUTORS.md).

    AGENTS.md compliance audit

    • Mantine conventions — N/A: no components/JSX/CSS touched (Markdown only).
    • TypeScript rules — N/A: no .ts/.tsx changed.
    • Coverage gate (≥90%) — N/A: no executable code, no coverage surface.
    • Issue/board policy consistency — ✅ Consistent. The issues-only policy (external contributors file issues; maintainers own design/implementation and open PRs) does not contradict AGENTS.md's issue-driven, board-tracked workflow. No contradictions found.

    Verdict

    Approve with a follow-up note. The policy doc is well-formed, welcoming, and internally correct — all links/anchors/cross-refs resolve and it satisfies requirements #1, #3, #4, #5, and the cross-reference. The gap is checklist item #2 (version-board + labeling-by-version guidance), which the PR body claims to cover but the file omits. Recommend either adding the small version-board/label table to the "How to contribute a bug report or feature request" section or correcting the PR description before merge. Nit #2 (PR-template link) is optional polish.

    Link/anchor check commands used 
    # anchor slug resolution (GitHub-style slugify) vs headings
git show origin/chore/1517-contributors-md:CONTRIBUTORS.md \
  | python3 -c 'import re,sys; t=sys.stdin.read(); \
    h=[re.sub(r"[^\w\s-]","",m.lower()).replace(" ","-") for m in re.findall(r"^#{1,6}\s+(.*)$",t,re.M)]; \
    [print(a, a in h) for a in re.findall(r"\(#([a-z0-9-]+)\)",t)]'

# claimed-vs-actual content probes (all returned 0)
grep -ciE 'board|label|v1\.5|Label by version|\|' CONTRIBUTORS.md
  6. cliffhall
    added 3 commits that reference this issue on Jul 2, 2026

    docs: add version-board/label table to CONTRIBUTORS.md (closes #1595)

    79ca8f0

    Merge pull request #1537 from modelcontextprotocol/chore/1517-contrib…

    7d4caf8

    revert(rollup): remove CONTRIBUTORS docs (#1537/#1517) from Wave-1 ro…

    859911d
  7. cliffhall
    linked a pull request that will close this issuedocs: add CONTRIBUTORS.md issues-only policy (closes #1517) #1604on Jul 2, 2026
  8. cliffhall
    removed a link to a pull requestdocs: add CONTRIBUTORS.md issues-only policy (#1517) #1537on Jul 2, 2026
  9. cliffhall
    added 5 commits that reference this issue on Jul 27, 2026

    docs: drop v1.5 from CONTRIBUTORS.md, invite deeper contribution (#1517)

    800c26a

    docs: drop project-board links from CONTRIBUTORS.md (#1517)

    1360398

    docs: v1 takes security fixes only (#1517)

    7f92365

    docs: use post-runbook branch names (v1/main, main) (#1517)

    4b9bc4a

    docs: add CONTRIBUTORS.md issues-only policy (closes #1517) (#1604)

    b3be65b

  10. cliffhall commented on Jul 27, 2026

    @cliffhall
    cliffhall
    on Jul 27, 2026
    MemberAuthor

    Shipped in #1604, merged to v2/main as b3be65b. Follow-up doc sweep (AGENTS.md / README.md branch references after the #1804 cutover) tracked in #1813.

  11. cliffhall
    closed this as completedon Jul 27, 2026
  12. pull
    added a commit that references this issue on Jul 28, 2026

    docs: add CONTRIBUTORS.md issues-only policy (modelcontextprotocol#1517)

    73d7439
  13. cliffhall
    added this to the v2.0.0 milestone on Jul 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

v2Issues and PRs for v2

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions