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.5 KiB
AGENTS.md
Instructions for a coding assistant working in this repository. A human owns every change you produce: your output is a draft until they have read it, run it, and can answer for it. CONTRIBUTING.md applies to you as written.
What the repository is
service/ is the Go service (API, settings database, transparent proxy, the core config it generates). core/ is v2raya_core, a fork of xray-core carrying the DNS module, the in-core TUN and the extra protocols. gui/ is the web interface: Vue 3, Vuetify 4 on Material 3, vue-i18n, Vitest. install/ is packaging. The service embeds the built web files.
Before you change anything
Read the code you are about to change and the code that calls it. Reuse the components and helpers that exist and follow the neighbouring file's conventions. Do not introduce a parallel implementation or a second convention.
If you cannot tell whether existing behaviour is intentional, ask the human before you change it.
What the change must satisfy
(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 ./...)
CI runs only the gui line and builds the binaries, so run all three yourself, from the repository root, and then exercise the change: for the service, start v2raya and use the feature; for the interface, open the page and use what changed. A description of behaviour you did not observe is worth nothing to the review. TestResolvHijackerConcurrentResetRemove fails for a non-root user; that one is known.
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.
Traps that cost a review round
go build ./...inservice/fails withpattern web: no matching files foundwhileservice/server/router/webis empty.yarn --cwd gui buildwrites toweb/at the root;./build.shcopies it across.- The locale files are
en, zh, fa-ir, ko, pt-br, ru; the documentation directories areen, zh, fa, ko, pt, ru. The names differ. Both sets change together. - A literal
@in a locale string must be written{'@'}; vue-i18n reads a bare one as a linked message. - A key that
i18n-checkcannot see statically belongs to a prefix listed ingui/scripts/i18n-check.mjs; add the prefix rather than the key. - Colours come from the Material scheme:
rgb(var(--v-theme-<role>)). Do not write a hex literal in a component; it cannot follow the theme. - Type comes from the scale in
gui/src/theme/typography.scss(md3-title-largeand the rest), which uses weights 400 and 500; do not add 700. core/is a fork of xray-core. v2rayA's own code iscore/dns,core/hintandcore/main; leave the rest to upstream. After editing a.protoundercore/hint/proxy, regenerate from the module root (protoc --go_out=. --go_opt=paths=source_relative hint/proxy/<name>/config.proto) so the descriptor keeps its path.- Read a command's exit code; do not infer success from the end of its output.
eslintprints its errors above the summary line. - A check that ran nothing proves nothing:
no test files, a-runpattern that matched no test, a search over no files. Say what ran.
Code in this repository
Match the file you are editing: its comment density, its naming, its idiom. Comments state what is not evident from the code — a reason, a constraint, a protocol quirk — and stop there; no comment repeats what the next line says.
Reach for what is already there before adding anything: a dependency the module already has, a helper in service/common or gui/src/lib, a Vuetify component before a hand-written one. A new dependency needs a reason a reviewer would accept.
What not to do
- Do not sign your work: no model
Co-Authored-Bytrailer, no AI signature, no generated-by marker, in a comment, a commit message or pull request text. - Do not touch code the change does not require: no reformatting, no renaming, no regenerated lockfiles.
- Do not present a guess as a result. If you did not run it, say so.
- Do not open or comment on an issue or a pull request on your own. Leave the "Submitted and answered for by" line and the boxes about what the human did or understands as the template has them, and tell the human to fill them in before submitting. The human submits, and answers for what is submitted.