Skip to content

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

Merged
cliffhall merged 8 commits into
v2/mainfrom
docs/1517-contributors-md
Jul 27, 2026
Merged

docs: add CONTRIBUTORS.md issues-only policy (closes #1517)#1604
cliffhall merged 8 commits into
v2/mainfrom
docs/1517-contributors-md

Conversation

@cliffhall

@cliffhall cliffhall commented Jul 2, 2026

Copy link
Copy Markdown
Member

Closes #1517

Adds CONTRIBUTORS.md (issues-only policy + version→board/branch/label table), the PR-template pointer, and an AGENTS.md ## Contributing link.

Provenance: this work was briefly folded into the Wave-1 rollup (1579-wave-1 / #1601) during review, then pulled back out — it's unrelated to the #1510 Apps-host decomposition that defines Wave 1. This PR is the real, standalone path to v2/main. Clean history (cherry-picked the doc commits onto v2/main, no rollup/merge/empty-commit noise). The old #1537 shows "merged into 1579-wave-1" from that interim step and is superseded by this.

cliffhall and others added 4 commits July 2, 2026 13:11
Document the contribution policy: we accept issues, not pull requests.
Maintainers handle design and implementation through a prompt-driven
workflow. Contributors who have already built a change locally should
share the prompt they used rather than a diff.

Cross-reference the policy from AGENTS.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…icy (#1517)

GitHub auto-populates pull_request_template.md into every new PR body,
so it steers would-be external PR authors to CONTRIBUTORS.md before they
submit a diff.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The policy takes effect after v2/main merges into main, leaving a single
line of development. Tell contributors to open a well-formed issue rather
than routing them to per-version project boards.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Completes requirement #2 of #1517: a table mapping each active version to
its base branch, project board, and version label, plus a "Label by
version" note mirroring AGENTS.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S3fTN8H3R8YV4yUGvZjYnX
@BobDickinson

Copy link
Copy Markdown
Contributor

I like this. I might remove the v1.5 references (and maybe kill the v1.5 branch altogether), since nobody outside of the core team probably ever saw that of knows what it is/was.

It might also be good to say that if you want to work on the project as part of the team, that we invite you to join us on Discord or attend our meetings. It seems like we need some way for someone who really is interested in volunteering either in general or in some specific area to be able to contribute under our supervision, with a possible path to becoming a maintainer. I'm not sure what that looks like, but I'm trying to make it seem like we've completely closed the door to people we really want to contribute a level that makes sense for us to support.

Review feedback on PR #1604:

- Remove the v1.5 row/bullet from the version table — v1.5 was an internal
  intermediate branch that external contributors never saw, so surfacing it
  in an outward-facing doc is noise. The table is now v1 / v2 only.
- Add a "Want to work on the Inspector with us?" section pointing at the MCP
  Contributor Discord (#inspector-dev) and the community calls, framing the
  issues-only rule as being about unsolicited patches rather than a closed
  door, with supervised work as the path toward maintainership.
- Link that section from "Why this policy exists", and add the same Discord
  pointer to the PR template.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD
@cliffhall

Copy link
Copy Markdown
Member Author

Both addressed in the latest commit.

1. v1.5 references removed. You're right that it's internal history nobody outside the core team ever saw — surfacing it in an outward-facing doc is just noise. The version table is now v1 / v2 only, and the "Label by version" line drops v1.5 too. I left the v1.5 notes in AGENTS.md alone: that's the maintainer-facing doc, and the "frozen, kept as a reference point, do not delete" note there is still useful to us (and to an agent) when chasing a regression from the merge into v2/main. Killing the branch itself is a separate call — happy to open an issue for it if you want to go that way.

2. Door left open. Added a "Want to work on the Inspector with us?" section that frames the issues-only rule as being about unsolicited patches, not about turning people away:

  • Join the MCP Contributor Discord and say hello in #inspector-dev — the existing channel for day-to-day Inspector development.
  • Attend the community calls at meet.modelcontextprotocol.io, with a pointer to the org's Contributor Communication page for the full channel list.
  • Explicit framing: from there we can scope a piece of work with you and supervise it through our workflow, "which is also the path toward becoming a maintainer" — contrasted against drive-by diffs. Plus a Code of Conduct link.

It's linked from "Why this policy exists" ("we'd rather bring you into the workflow than turn you away"), and I added the same #inspector-dev pointer to the PR template so someone who gets bounced from opening a PR immediately sees where to go instead.

Existing channels are used rather than inventing new ones, so nothing here needs standing up. If you'd rather point at a dedicated Inspector meeting slot or a different escalation path, tell me what it is and I'll swap it in.

cliffhall and others added 3 commits July 27, 2026 18:45
The org project boards aren't visible to anyone outside the organization, so
linking them in an outward-facing doc points contributors at a 404. The
version table is now base branch + label only, and the PR template names the
version labels instead of "the appropriate version board".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD
This doc will be read after the branch runbook completes, when v1 lives on
v1/main and v2 is the default main. Update the version table, the label-by-
version line, and the PR template's label hint + CONTRIBUTORS.md links
accordingly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD
@cliffhall
cliffhall merged commit b3be65b into v2/main Jul 27, 2026
1 check passed
@cliffhall
cliffhall deleted the docs/1517-contributors-md branch July 27, 2026 23:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

v2 Issues and PRs for v2

Projects

None yet

2 participants