Skip to content

docs: rename CONTRIBUTORS.md to CONTRIBUTING.md so GitHub surfaces the policy - #1884

Merged
cliffhall merged 3 commits into
v2/mainfrom
v2/docs/1883-rename-contributing
Aug 1, 2026
Merged

docs: rename CONTRIBUTORS.md to CONTRIBUTING.md so GitHub surfaces the policy#1884
cliffhall merged 3 commits into
v2/mainfrom
v2/docs/1883-rename-contributing

Conversation

@cliffhall

Copy link
Copy Markdown
Member

Closes #1883

Sub-task of #1821.

What changed

  • git mv CONTRIBUTORS.md CONTRIBUTING.md — a pure rename, zero content changes (git show --stat reports CONTRIBUTORS.md => CONTRIBUTING.md | 0), so history follows the file. Its heading already reads "Contributing to MCP Inspector".
  • AGENTS.md — the one in-repo reference, in the Contributing section:
    See [CONTRIBUTORS.md](./CONTRIBUTORS.md) for the full policy.See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full policy.

I re-grepped (git grep -n CONTRIBUTORS) across .github/, README.md, docs/, clients/*/README.md, and specification/. On v2/main today the only other hits are the two links in .github/pull_request_template.md, which are deliberately left alone — open PR #1879 makes both of them relative so they follow the rename automatically, and editing them here would collide with it. (There is no SECURITY.md on v2/main, so nothing to sweep there.)

Why it matters

GitHub's contributing-guidelines affordance — the banner surfaced when someone clicks New issue or opens a pull request — keys on the exact filename CONTRIBUTING.md. v2 named the file CONTRIBUTORS.md, so that prompt was dark in exactly the place the "open an issue, not a PR" policy needs to land. Renaming lights it up, and it removes the need for the redirect-stub alternative considered in #1870 (which would have left two files to keep in sync).

⚠️ Dependency on #1866 — required post-merge sweep

PR #1866 (v2/docs/post-swap-branch-model-and-pr-policy) modifies both CONTRIBUTORS.md and AGENTS.md, and merges before this one. This PR is branched from v2/main, not stacked on #1866, per the plan in #1883.

Git resolves the rename/modify pair on the file itself automatically (rename detection replays #1866's edits onto CONTRIBUTING.md), so the renamed file is not the problem. What is a problem: #1866 introduces a new reference to the old filename that does not exist on v2/main yet, so it cannot be fixed in this PR. After both land, sweep it:

File Line #1866 introduces (quoted) Fix
AGENTS.md If you've already built a change locally, share the **prompt** you used and screenshots if applicable, not a diff. See [`CONTRIBUTORS.md`](./CONTRIBUTORS.md) for the full policy. Replace both the link text and the target with CONTRIBUTING.md

That is the complete list — gh pr diff 1866 touches four files (.github/copilot-instructions.md, AGENTS.md, CONTRIBUTORS.md, README.md) and the only added line mentioning the old name is the AGENTS.md one above. (The other CONTRIBUTORS.md occurrences in that diff are the removed original of this same line and the diff's own a//b/ path headers, which the rename handles.)

Note also that #1866 rewrites the very line this PR edits, so if git flags a textual conflict in AGENTS.md, resolve it by taking #1866's rewritten sentence with CONTRIBUTING.md substituted for CONTRIBUTORS.md — i.e. exactly the table row above.

Known, accepted breakage

External links to blob/*/CONTRIBUTORS.md — including in already-posted PR/issue comments — will 404. GitHub does not redirect deleted paths; this is called out and accepted in #1883.

Testing

Docs-only rename; no code paths touched, so no build/test surface is affected.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YAt8rqxysNbhYWLhoRm3fU

GitHub's contributing-guidelines banner — shown when someone clicks
"New issue" or opens a pull request — keys on the exact filename
CONTRIBUTING.md. Naming the file CONTRIBUTORS.md left that prompt dark
precisely where the "open an issue, not a PR" policy needs to land.

Renamed with `git mv` so history follows the file; contents are
unchanged (its heading already reads "Contributing to MCP Inspector").
Updated the one in-repo reference, in AGENTS.md. The two links in
.github/pull_request_template.md are deliberately untouched — PR #1879
makes them relative so they follow the rename.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YAt8rqxysNbhYWLhoRm3fU
@cliffhall cliffhall added the v2 Issues and PRs for v2 label Aug 1, 2026
@cliffhall
cliffhall requested a review from Copilot August 1, 2026 02:44

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Renames the repository’s contributing-policy document to CONTRIBUTING.md so GitHub’s built-in contributing-guidelines affordance is enabled, and updates the in-repo reference in AGENTS.md to match the new filename.

Changes:

  • Adds/renames the contributing guidelines document to CONTRIBUTING.md.
  • Updates AGENTS.md to link to CONTRIBUTING.md instead of CONTRIBUTORS.md.

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated 1 comment.

File Description
CONTRIBUTING.md Contributing policy document intended to be surfaced by GitHub’s UI.
AGENTS.md Updates the contributing-policy link to the new filename.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread AGENTS.md Outdated
Comment on lines +109 to +112
External contributions are accepted as **issues, not pull requests** —
maintainers handle design and implementation through a prompt-driven workflow.
If you've already built a change locally, share the **prompt** you used, not a
diff. See [`CONTRIBUTORS.md`](./CONTRIBUTORS.md) for the full policy.
diff. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full policy.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct observation, but intentionally out of scope here — declining in this PR.

.github/pull_request_template.md is already owned by open PR #1879, which converts both of its links to repo-relative form so they follow this rename automatically. Editing the same two lines here would collide with that PR for no benefit, so #1883 explicitly scopes them out ("#1879 already handles the PR-template links... Don't re-fix them here").

The redirect-stub alternative you mention was considered in #1870 and rejected — it leaves two files to keep in sync, which is exactly what this rename removes.

Sequencing, so nothing is left dangling: #1879 lands the relative links, this PR lands the rename, and the PR body enumerates the one remaining post-merge sweep item (the new CONTRIBUTORS.md reference that #1866 adds to AGENTS.md, which doesn't exist on v2/main yet and so can't be fixed from this branch).

This PR edited the `See [CONTRIBUTORS.md](./CONTRIBUTORS.md)` link in
AGENTS.md, which is the exact line #1866 rewrites — guaranteeing a one-line
conflict when this merges after it.

Handing that line to its owner instead: #1866 now writes the link as
`CONTRIBUTING.md` directly, so this PR is a pure `git mv` and the two touch no
common line. No conflict to resolve at merge time.

The tradeoff is a short window between the two merges where AGENTS.md links to
a filename that doesn't exist yet. That's deliberate and bounded: #1866 is
first in the merge order and this is third.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YAt8rqxysNbhYWLhoRm3fU
cliffhall added a commit that referenced this pull request Aug 1, 2026
This PR rewrites the paragraph holding the only in-repo link to the
contributing policy, so it owns that line. #1884 renames the file
CONTRIBUTORS.md -> CONTRIBUTING.md; having #1884 also edit this line would
guarantee a one-line conflict between the two.

Writing the new filename here instead makes #1884 a pure `git mv` with no
overlapping line, so neither PR conflicts with the other.

Between this merging and #1884 merging, the link points at a filename that
doesn't exist yet. That window is deliberate and bounded — this PR is first in
the merge order (#1821) and #1884 is third.

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

Copy link
Copy Markdown
Member Author

Reduced to a pure rename so this can't conflict with #1866.

The AGENTS.md link edit is gone from this PR. #1866 rewrites that exact line, so keeping it here guaranteed a one-line conflict at merge time; instead #1866 now writes the link as CONTRIBUTING.md itself (its commit). The two PRs now share no file and no line.

This also retires the post-merge sweep enumerated in the description above — there is nothing left to sweep, since the one reference #1866 introduces already points at the new name.

Tradeoff, stated plainly: between #1866 merging and this merging, AGENTS.md links to a filename that doesn't exist yet. That window is deliberate and bounded — #1866 is first in #1821's merge order and this is third.

Note the rename/modify relationship still exists at the git level (#1866 edits CONTRIBUTORS.md's contents; this renames it). That's the case git's rename detection resolves automatically, applying #1866's edits to the renamed file. What's been eliminated is the line-level conflict, which git could not have resolved on its own.

cliffhall added a commit that referenced this pull request Aug 1, 2026
…review instructions (#1866)

* docs: correct post-swap branch model, PR policy, and stale gate/tree entries

Part of the go-live phase-8 docs hygiene: everything that silently inverted
when `main` became v2.

Branch/release model — documented canonically in AGENTS.md and corrected
everywhere it was restated:
- AGENTS.md: replace the one-line "Base Branches" bullet with a table giving
  each branch its role (v2/main = develop, main = release, v1/main =
  maintenance), whether PRs target it, and which npm dist-tag it publishes.
- README.md: the "Repo status" callout had it backwards, claiming `main` was
  the legacy v1 implementation. Also note that a v2 release is cut from `main`
  after the milestone merge, not from v2/main.
- CONTRIBUTORS.md: the version table listed v2's base branch as `main`.

PR policy:
- Every PR must reference an issue, from anyone, no exceptions.
- PRs are opened by repo maintainers only — org write access is not
  authorization. Everyone else files a detailed issue.
- Branch names start with the target version segment (v2/…, v1/…).
- Issues and PRs carry exactly one of `v1`/`v2` at creation; default `v2`.
- Screenshots proving UI/TUI changes go in the gitignored pr-screenshots/.

Corrections to stale content found while in there:
- The TUI coverage bullet still described the Ink/App.tsx/hooks exclusion as
  interim pending #1501, which closed 2026-06-29; the gate now covers all of
  src/** with only tui-servers.ts excluded.
- The completion checklist said `npm run validate` was the gate and covered
  "e2e tests", contradicting the mandatory-pre-push-gate section (npm run ci).
- v1 PR base was given as `main`; it is `v1/main`.
- Project tree omitted core/client, docs/, and scripts/ (README: core/client,
  docs/). core/client is under the coverage gate and imported by both App.tsx
  trees.

Also adds the launcher and `npm run test:scripts` to the "run the tests" list
and a tiers overview, since neither was mentioned.

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

* docs: require a milestone on every new issue, defaulting to the current one

Adds the rule alongside the version-label rule, since they fail the same way:
an unmilestoned issue drops out of release planning as silently as an
unlabeled one drops out of version filtering.

- Set it at create time (`gh issue create --milestone <title> ...`).
- If the user didn't specify one, default to the current milestone — the open
  milestone with the nearest due date — rather than leaving it blank pending a
  decision. Includes the `gh api .../milestones` one-liner that identifies it.
- Milestones are release buckets, so pick by when the work ships, not by size;
  sub-issues normally inherit their parent's milestone.

Also widens the section's opening callout: an issue is not "created" until it
is labeled, milestoned, AND boarded with a Status — four distinct steps, not
three.

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

* docs: add .github/copilot-instructions.md and require mirroring into it

GitHub Copilot reads .github/copilot-instructions.md when reviewing a PR. The
repo had no such file, so Copilot reviewed without any of the conventions that
actually govern this codebase — the ban on `any` and on unjustified double
casts, the Mantine-first styling rules, the `.withProps()` extraction rule, the
lib/utils split, test placement, and the per-file >=90% four-dimension gate.

The new file is a review-focused distillation of AGENTS.md: the rules a
reviewer would cite against a diff, plus a short "what to prioritize" list that
puts correctness and security first (this backend spawns processes and proxies
outbound requests). Deliberately omitted: board recipes and IDs, milestone and
branch mechanics, release procedure, and the project tree — no reviewer cites
those, and copying them would double the maintenance surface.

AGENTS.md's "Keep documentation files up to date" section now requires
mirroring review-relevant changes into it in the same PR, states that AGENTS.md
stays the source of truth, and spells out what counts as review-relevant. There
is no generation step and nothing detects drift, so the rule is the only thing
keeping the two in sync.

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

* docs: address Copilot review — v1 policy wording, stale V2 Go Live, typo

- Align the v1 maintenance policy on "security and bug fixes only" in
  AGENTS.md and CONTRIBUTORS.md; both said "security fixes only" while the
  README callout, the branch table, and the board description said
  "security and bug fixes".
- Drop the stale "or V2 Go Live" instruction from the work-begins step —
  that column no longer exists on board #28 (verified via
  `gh project field-list 28`), so the option id it implied would be
  rejected. Restore the removed-column id list the same edit dropped, now
  including V2 Go Live, and re-date the table to today's verification.
- Fix "contains the the new version" typo.
- Strip a stray trailing blank line at the end of AGENTS.md.

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

* docs: restore `inspector/` as the Project Structure tree root

The tree is a filesystem layout — every child is a real directory
(`clients/`, `core/`, `test-servers/`). Labeling its root `v2/main/` named
a branch instead, which reads as a path that does not exist in a checkout
and diverged from the identical tree in README.md, which still says
`inspector/`. The branch model is documented in its own table under
Repository & Project Boards; the tree does not need to restate it.

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

* docs: settle the v1 policy wording as "security fixes only"

Reverses the direction the Copilot round took in 33cc036. That commit
normalized the six v1-policy sites onto "security and bug fixes" because that
was the majority wording — but majority is the wrong tiebreak here. The policy
is set by what we told contributors: the #1819 backlog close note, posted to
120 closed PRs, says "v1 will receive security fixes only", and the five PRs
retained for 1.0.5 are all security fixes.

So the two sites that already said "security fixes only" were the correct ones,
and the four that said otherwise are now aligned to them:

- AGENTS.md: the `v1` label description, the branch-role table, and the v1
  board line.
- README.md: the "Repo status" callout.

CONTRIBUTORS.md and AGENTS.md's Project Status bullet already read correctly
and are unchanged.

This is the substance of #1813, which is why that issue's PR is now reduced to
its PR-template-link half — the wording work landed here to avoid two PRs
editing the same lines in opposite directions.

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

* docs: point the AGENTS.md policy link at CONTRIBUTING.md

This PR rewrites the paragraph holding the only in-repo link to the
contributing policy, so it owns that line. #1884 renames the file
CONTRIBUTORS.md -> CONTRIBUTING.md; having #1884 also edit this line would
guarantee a one-line conflict between the two.

Writing the new filename here instead makes #1884 a pure `git mv` with no
overlapping line, so neither PR conflicts with the other.

Between this merging and #1884 merging, the link points at a filename that
doesn't exist yet. That window is deliberate and bounded — this PR is first in
the merge order (#1821) and #1884 is third.

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

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
@cliffhall
cliffhall merged commit 379a8a0 into v2/main Aug 1, 2026
1 check passed
@cliffhall
cliffhall deleted the v2/docs/1883-rename-contributing branch August 1, 2026 03:02
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

Development

Successfully merging this pull request may close these issues.

2 participants