Zakk
154f016fdd
The repository had six markdown issue templates, no pull request template and no guide, so a report rarely said which version it was and a pull request rarely said what its author had run. The issue templates become four GitHub forms, English and Chinese kept apart, asking for the version and why it is not the latest, the system and install method, the transparent proxy mode, the steps, the logs and the person who answers for the report. Usage questions go to Discussions through config.yml, and blank issues are off. The pull request template, also in two languages, asks for the change in the author's own words, what was executed and observed, and a checklist of what the review expects; two of its boxes are true only of someone who checked the list without reading it, or of an agent submitting without human review, and checking either one closes the pull request. CONTRIBUTING.md says where the code lives, what to run before opening a pull request, that all six locales change together and that no AI attribution goes into the history. AGENTS.md tells an assistant the same in its own terms, with the traps that cost a review round: the web files the service embeds, the locale and documentation directories that are named differently, the escaped @ in a locale string, the Material colour and type tokens, and what in core/ belongs to v2rayA rather than to xray-core.
3.3 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.26 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 the checks CI runs, from the repository root:
(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.
- 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.
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.