docs: CONTRIBUTOR.md

2026-06-27 18:56:21 +08:00
1 parent 7b458daf77
commit 51c9eab4e2
@@ -0,0 +1,325 @@
+# Felis Contributor Guide
+
+This document is the practical entry point for contributors. It focuses on how to
+run, test, and reason about the project while keeping changes small and aligned
+with the current codebase.
+
+## Project Shape
+
+Felis is a Kubernetes-native Minecraft server control plane. The repository has
+four main areas:
+
+- `cmd/felis/`: the single Go CLI binary. It dispatches subcommands such as
+  `api`, `operator`, `migrate`, `reaper`, `restore`, `manifests`, and
+  `breakGlass`.
+- `internal/`: backend packages for API handlers, store migrations, Kubernetes
+  rendering, operator reconciliation, build, backup, restore, and related domain
+  logic.
+- `panel/`: the React/Vite web control panel.
+- `plugins/`: Minecraft-side plugins and mods for Velocity, Paper, Fabric,
+  Forge, and NeoForge.
+
+The codebase is intentionally split by responsibility. Prefer changing the
+smallest owning module instead of adding broad abstractions or rebuilding nearby
+code.
+
+## Local Development
+
+You can do most day-to-day development on macOS or Linux without a full cluster.
+The full product needs Postgres and Kubernetes, but unit tests and frontend work
+run locally.
+
+Recommended local tools:
+
+- Go matching `go.mod`
+- Node.js and npm for `panel/`
+- Optional: JDK/Gradle for plugin work
+- Optional integration environment: a clean Linux VM or server with Docker,
+  k3s, and Postgres
+
+Check tool versions:
+
+```bash
+go version
+node --version
+npm --version
+java -version
+```
+
+## Backend Commands
+
+Run these from the repository root:
+
+```bash
+cd /path/to/Felis
+```
+
+Run all Go tests:
+
+```bash
+go test ./...
+```
+
+Run a focused package:
+
+```bash
+go test ./internal/api
+go test ./cmd/felis
+```
+
+Build the CLI:
+
+```bash
+go build -o /tmp/felis-dev ./cmd/felis
+/tmp/felis-dev help
+```
+
+Render Kubernetes manifests without contacting a cluster:
+
+```bash
+/tmp/felis-dev manifests \
+  --felis-image registry.felis.svc:5000/felis:dev \
+  --velocity-cidr 10.0.0.5/32
+```
+
+`felis api`, `felis operator`, `felis migrate up`, and `felis reaper` are real
+runtime commands. They need external services such as Postgres and/or a
+Kubernetes config, so they are not the first choice for quick local iteration.
+
+## Frontend Commands
+
+Run these from the frontend workspace:
+
+```bash
+cd /path/to/Felis/panel
+```
+
+Install dependencies:
+
+```bash
+npm ci
+```
+
+Run against a real backend at `http://localhost:8080`:
+
+```bash
+npm run dev
+```
+
+Run with the local mock API:
+
+```bash
+npm run dev:mock
+```
+
+The mock dev server prints its accounts, link code, and reset command when it
+starts. Use it for frontend work when you do not have the Go API and cluster
+running.
+
+Common frontend checks:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```
+
+## Mock API
+
+The frontend mock API lives under `panel/dev/` and is loaded only by
+`npm run dev:mock`. It must not leak into production code or business
+components.
+
+Run mock commands from the frontend workspace:
+
+```bash
+cd /path/to/Felis/panel
+npm run dev:mock
+```
+
+Current mock accounts:
+
+| Username | Password | Scenario |
+| --- | --- | --- |
+| `owner` | `devpassword` | admin, linked |
+| `user` | `devpassword` | normal user, not linked |
+| `linked` | `devpassword` | normal user, linked |
+| `setup` | `devpassword` | admin, first-login password change |
+
+Mock Minecraft link code:
+
+```text
+LINK1234
+```
+
+Reset mock state:
+
+```bash
+curl -X POST http://127.0.0.1:5173/api/v1/__mock/reset
+```
+
+Mock rules:
+
+- Keep mock-only logic in `panel/dev/`.
+- Do not import mock code from `panel/src/`.
+- Keep response shapes aligned with `panel/src/lib/types.ts` and the Go API
+  handlers.
+- Prefer realistic error codes over happy-path-only mocks.
+- Do not present mock data as live production data.
+
+## Full Integration Environment
+
+Run integration/deploy commands from the repository root on the Linux host:
+
+```bash
+cd /path/to/Felis
+```
+
+The one-line bootstrap script is intended for a clean Linux host, not a typical
+macOS development machine:
+
+```bash
+sudo -E bash deploy/bootstrap.sh
+```
+
+Useful overrides:
+
+```bash
+export FELIS_REPO_URL=<your fork url>
+export FELIS_REF=<your branch>
+export FELIS_IMAGE=felis:dev
+export FELIS_ROOT_DOMAIN=<node-ip>.nip.io
+```
+
+The bootstrap flow installs/configures system services, builds the Felis image,
+imports it into k3s, runs migrations, applies CRDs/manifests, and deploys the
+control plane.
+
+After bootstrap, use the break-glass console to create or recover the Owner
+account:
+
+```bash
+sudo felis breakGlass
+```
+
+Use a VM or disposable Linux server for this. Treat it as an integration and
+acceptance environment, while keeping normal coding and quick tests local.
+
+## Plugin Development
+
+Plugin docs live in `plugins/README.md`.
+
+The plugin modules intentionally use separate Gradle builds:
+
+```bash
+# cwd: repository root
+cd /path/to/Felis
+
+gradle -p plugins/velocity build
+gradle -p plugins/paper build
+bash plugins/fabric/gradlew -p plugins/fabric build
+bash plugins/forge/gradlew -p plugins/forge build
+bash plugins/neoforge/gradlew -p plugins/neoforge build
+```
+
+Notes:
+
+- Fabric/Forge/NeoForge use module wrappers.
+- Velocity/Paper use system Gradle.
+- Most modules target Java 17.
+- Paper needs a Java 21 toolchain.
+- First builds may be slow because Minecraft dependencies are downloaded and
+  remapped.
+
+## Frontend Status
+
+The panel is currently an early control-panel implementation, not a complete
+product.
+
+Reasonably usable today:
+
+- Local-password login
+- First-login password change
+- User/admin route gates
+- Dashboard shell
+- My servers list
+- Wake, stop, claim actions
+- Read-only console log stream
+- Account linking flow
+- Admin create-server form
+- Read-only image whitelist
+- Mock API for local frontend work
+
+Still shallow or missing:
+
+- Server detail depth
+- Log search/filter/download
+- RCON command UX, if/when the backend path is ready
+- Admin edit/delete/transfer flows
+- Image whitelist mutations
+- Backups and restore UI
+- Fleet-wide ops data
+- Stronger component and browser-level tests
+
+When adding frontend features, keep UI state honest. If the backend endpoint does
+not exist yet, use an explicit placeholder instead of fake live data.
+
+## i18n Notes
+
+i18n is not yet established as a full system. User-facing strings are currently
+mostly inline in TSX and helper functions.
+
+Good first targets:
+
+- Error messages mapped from stable API error codes
+- Navigation labels
+- Page titles and primary actions
+- Phase/status labels
+- Empty/loading/error states
+
+Recommended initial approach:
+
+```text
+panel/src/i18n/
+  index.ts
+  en.ts
+  zh-CN.ts
+```
+
+Use a small typed dictionary first. Add a larger library such as
+`i18next/react-i18next` only when the project needs runtime language switching,
+pluralization rules, external translation workflows, or more complex
+localization behavior.
+
+Do not translate code comments, internal logs, or mock-only terminal messages
+unless there is a clear contributor need.
+
+## Contribution Style
+
+Follow the existing code. Keep changes narrow and easy to review.
+
+Guidelines:
+
+- Prefer minimal changes over rewrites.
+- Do not add a new abstraction unless it removes real duplication or names a
+  strong local concept.
+- Keep frontend mock code out of business components.
+- Keep backend tests close to the package that owns the behavior.
+- Preserve public API and persistence shapes unless the change explicitly needs a
+  contract update.
+- Do not commit generated build output such as `panel/dist/`, `node_modules/`,
+  Gradle build directories, or local binaries.
+
+AI-assisted work is welcome, but the contributor is responsible for the result.
+Do not submit a PR that is entirely AI-generated and not personally reviewed.
+Low-quality AI dumps, broad rewrites that ignore the current design, unverified
+changes, or code the author cannot explain will not be accepted.
+
+Before handing off a change, run the smallest meaningful checks:
+
+```bash
+go test ./...
+cd panel && npm run typecheck && npm test && npm run build
+```
+
+If you cannot run a relevant check, say so explicitly in the handoff.