Files
v2rayA/CONTRIBUTING.md
Zakk 9fba5a63b1 docs: tighten the contribution rules for assisted pull requests
Recent pull requests left the "Submitted and answered for by" line
filled in by an assistant or dropped, kept a commit that a later
commit reverted, and described changes their diff no longer had.
CONTRIBUTING.md also told contributors to run "the checks CI runs",
but CI runs neither go vet nor go test, and it named Go 1.26 while
core/ needs 1.27.

- CONTRIBUTING.md: Go 1.27; say which checks CI runs; squash a commit that undoes part of an earlier one; a bug fix
  comes with a failing test or a reproduced failure; check the title,
  description and messages against the diff; the sign-off line and the
  boxes are the contributor's.
- AGENTS.md: ask before changing behaviour that may be intentional; a
  check that ran nothing proves nothing; leave the sign-off line and
  the human's boxes alone.
- Pull request templates: the sign-off line is required and written by
  the contributor.
2026-11-13 02:17:08 +11:00

4.0 KiB

Contributing to v2rayA

Usage questions go to Discussions. Issues are for a defect or a feature request, pull requests for a change you have built and run. The issue forms and the pull request template come in English and Chinese; pick either.

Before you open an issue or a pull request, check the latest release: fixes go into the current release only. Then search the existing issues.

The repository

Where What
service/ the Go service: API, settings database, transparent proxy, the generated core config
core/ v2raya_core, a fork of xray-core with the DNS module, the in-core TUN and the extra protocols
gui/ the web interface: Vue 3, Vuetify 4 (Material 3), vue-i18n, Vitest
install/ packaging: systemd and OpenRC units, AUR, Docker, the Windows installer

./build.sh, from the repository root, builds the web interface and both binaries; it needs Go 1.27 and Node 24 with yarn. The service embeds service/server/router/web, which only build.sh fills: yarn --cwd gui build writes to web/ at the root, and go build in service/ fails until those files are copied across.

Before a pull request

Run these checks from the repository root. CI runs the gui line and builds the binaries; it does not run go vet or go test, so a pull request that skips them locally is untested.

(cd gui     && yarn lint && yarn typecheck && yarn i18n-check && yarn test && yarn build)
(cd service && go build ./... && go vet ./... && go test ./...)
(cd core    && go build ./... && go vet ./...)

Then exercise the change in the running program: a service change by starting v2raya and using the feature, a GUI change in a browser, at phone width and in both themes. TestResolvHijackerConcurrentResetRemove fails when the tests run as a non-root user; that one is known.

  • One change per pull request, and each commit a coherent step of it: no mixed-up commits, no reformatting of untouched code, no lockfile churn. A commit that undoes part of an earlier one in the same pull request is squashed into it before you push.
  • A bug fix adds a test that fails without the fix. Where no test can (packaging, CI, documentation), the Verification section gives the command that showed the failure and then the fix.
  • Before you submit, read the title, the description and every commit message against git diff main..., and remove anything they describe that the diff does not contain.
  • Visible text lives in gui/src/locales/: update all six locales together. yarn i18n-check compares key sets, not whether a translation followed a wording change. The in-app documentation under gui/src/docs/ has the same six.
  • Do not add a model Co-Authored-By trailer, an AI signature or a generated-by marker to a commit, pull request text or a comment.
  • One topic per commit, imperative subject saying what changes, fix: / feat: / docs: / ci: as the history uses.

AI-assisted contributions

An assistant may write and test the code, and you verify it before you submit it. Point it at AGENTS.md, which states what this repository expects of it.

  • Read its output before you push. If you cannot say why a line is there, it does not go in.
  • Execute what it wrote. Do not present an untested fix as verified.
  • Watch for the wrong root cause, argued well. Ask what else could produce the symptom.
  • Keep the diff to the change; do not let the assistant tidy unrelated code or regenerate lockfiles.
  • Between review rounds, be able to say in one sentence what changed and why.
  • Say which part it wrote. That is not held against you; hiding it is.
  • The "Submitted and answered for by" line and the boxes about what you did are yours. An assistant leaves them as the template has them.

Maintainers close an issue or a pull request submitted without human verification, or with a checklist checked without reading. Each checklist carries two statements that are false for an honest submitter; checking either one is the admission.