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.
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-checkcompares key sets, not whether a translation followed a wording change. The in-app documentation undergui/src/docs/has the same six. - Do not add a model
Co-Authored-Bytrailer, 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.