Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
50 lines (33 loc) · 2.43 KB

CONTRIBUTING.md

File metadata and controls

50 lines (33 loc) · 2.43 KB
Raw

Contributing to Neko Master

English | 中文

Thanks for contributing! This guide covers the development workflow for humans; if you develop with an AI coding tool (Claude Code, Copilot, Cursor, Codex, ...), point it at AGENTS.md — it holds the full conventions, key contracts, and task-specific workflow guides (.claude/skills/).

Development setup

  • Node.js 22, pnpm; Go 1.22+ only if you touch apps/agent.
pnpm install
pnpm dev            # starts web (3000) + collector (3001/3002)

Monorepo layout: apps/web (Next.js frontend), apps/collector (Fastify + SQLite backend), apps/agent (Go probe), packages/shared (shared types).

Before you open a PR

Run the checks for the areas you touched (details: verify-changes skill):

pnpm --filter @neko-master/collector exec tsc --noEmit
pnpm --filter @neko-master/collector test
pnpm --filter @neko-master/web exec tsc --noEmit
pnpm --filter @neko-master/web exec next build     # for production-impacting web changes
cd apps/agent && go vet ./... && go test ./...      # for agent changes

Requirements:

  • Tests: new backend behavior needs a Vitest case (helpers in apps/collector/src/__tests__/helpers.ts).
  • i18n: user-facing strings go through next-intl with keys in BOTH apps/web/messages/zh.json and en.json.
  • Dark mode: check every visual change in both themes — light-only Tailwind classes are the most common review comment.
  • Schema/stats changes: follow the add-stats-dimension checklist — several registries must change together.
  • New env vars: document them in .env.example.

Commits and PRs

  • Conventional-commit style: fix(collector): ..., feat(web): ..., docs: ....
  • Keep PRs focused; explain the user-visible effect and how you verified it.
  • English for code identifiers, comments, and commit messages; docs are bilingual where a .zh.md counterpart exists.

Releases (maintainers)

Tag-driven: vX.Y.Z builds Docker images, agent-vX.Y.Z builds agent binaries. Full flow: release skill and docs/release-checklist.md.

Reporting issues

Use the issue templates; include your deployment method (Docker/compose), version, gateway type (mihomo/Surge/OpenClash), and relevant collector logs.