Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (84 loc) · 5.13 KB

CONTRIBUTING.md

File metadata and controls

105 lines (84 loc) · 5.13 KB
Raw

Contributing to ReviewGuard MCP

Contributions are welcome. Contributions are accepted under the project's MIT license.

Contributor License Agreement (CLA)

All contributors are required to sign a CLA, which will be checked automatically when you open a pull request.

Development setup

Development requires npm >= 12 and a Node.js version npm 12 supports: 22.22.2 or newer on the 22 line, 24.15.0 or newer on the 24 line, or any later major. Both are enforced through the devEngines field in package.json. .nvmrc selects Node 24, the recommended version, for nvm use.

git clone https://github.com/eclipsesource/review-guard.git
cd review-guard
npm ci

npm 12 note: dependency install scripts are blocked by default. The ones this project needs are pre-approved in the allowScripts field of package.json, so a plain npm ci works. If a future dependency needs a script, review it first and approve it with npm install-scripts approve <pkg> so the allowance is committed.

Scripts

Command Purpose
npm run build Compile TypeScript to dist/
npm run dev Watch mode via tsx (requires a GitHub token)
npm start Run the HTTP server from source
npm run typecheck Type-check sources, tests, and configs
npm run lint ESLint (lint:fix to autofix)
npm run format Prettier write (format:check to verify only)
npm test Run the vitest suite (test:watch for watch)
npm run test:coverage Test with V8 coverage
npm run test:integration Manual run against a real GitHub repository (see below)

Integration tests (manual)

The unit suite mocks the GitHub API, so it verifies what the code sends but not how GitHub actually behaves. npm run test:integration closes that gap: it drives every MCP tool against a real repository and verifies each step with direct API reads independent of the code under test. Run it manually before a release or after dependency updates. It never runs in CI and the regular npm test does not pick it up.

It needs a private throwaway repository and two GitHub accounts with write access to it, because several checks involve a second user: draft invisibility, the foreign-thread resolve refusal, and reaction visibility. Configure it through environment variables:

Variable Meaning
REVIEW_GUARD_TEST_REPO The test repository as owner/name
REVIEW_GUARD_TEST_TOKEN_REVIEWER Token of the reviewer account under test
REVIEW_GUARD_TEST_TOKEN_AUTHOR Token of a second account that authors the pull request 
REVIEW_GUARD_TEST_REPO=me/review-guard-testbed \
REVIEW_GUARD_TEST_TOKEN_REVIEWER=ghp_... \
REVIEW_GUARD_TEST_TOKEN_AUTHOR=ghp_... \
npm run test:integration

The suite creates a branch and a pull request (authored by the second account), walks the full tool surface (pending review lifecycle, submit with the fixed disclaimer, own-thread resolution, the foreign-thread refusal, reaction visibility, PR scoping), and then closes the pull request and deletes the branch. Set REVIEW_GUARD_TEST_KEEP=1 to keep both for inspection. Leftovers from crashed runs are cleaned up at the start of the next run.

Pull requests

  • CI must pass: lint, format check, typecheck, build, tests, and a package dry-run.
  • New behavior needs tests. The safety guarantees in src/github.ts and the CLI validation in src/args.ts are covered by test/. Changes to either must keep or extend that coverage.
  • Keep the safety invariants documented in the README intact. Never add a second call site for submitPullRequestReview and never make the submit disclaimer removable.
  • Write plain sentences in docs, comments, and user-facing strings. No em dashes and no semicolons in prose.

Use of AI tools

Contributors can use whatever tools they would like to craft their contributions, but there must be a human in the loop. Contributors must read and review all LLM-generated code or text before they ask other project members to review it. The contributor is always the author and is fully accountable for their contributions. Contributors should be sufficiently confident that the contribution is high enough quality that asking for a review is a good use of scarce maintainer time, and they should be able to answer questions about their work themselves during review.

Releasing

Maintainers release through the Release GitHub Actions workflow. The full process, including the one-time npm trusted publishing setup, is documented in the repository wiki.