diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..d12e3f10 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,44 @@ +# CODEOWNERS — https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners +# +# Rules are matched bottom-up: the LAST matching pattern wins, so the broad +# default comes first and the narrow overrides below it. Only the last match is +# used, not a union — putting a specific path above `*` does nothing. +# +# The default is the `maintainers` team, which exists and has `@TyperBody` as a +# maintainer. A reference to something that does not exist fails silently: +# GitHub requests nobody and the PR merely looks owned. Add people to the team +# rather than swapping the handle here. +# +# Every change needs a named reviewer from that team. + +* @E-SPower/maintainers + +# Protocol v3, signing and the message field contract. A break here is expensive +# to undo, so it does not ride along in a larger PR unreviewed. +/backend/internal/protocol/ @E-SPower/maintainers +/backend/internal/messagefields/ @E-SPower/maintainers +/docs/developer-guide/protocol-v3.md @E-SPower/maintainers +/docs/developer-guide/message-fields.md @E-SPower/maintainers + +# Platform registry: matrix.json generates public Go code and a public doc, so a +# matrix edit is a code change even when the diff is one JSON line. +/matrix.json @E-SPower/maintainers +/scripts/gen_platformspec.py @E-SPower/maintainers +/scripts/gen_capabilities.py @E-SPower/maintainers +/scripts/check_generated.py @E-SPower/maintainers +/backend/internal/platformspec/ @E-SPower/maintainers + +# The merge gate itself — workflows, template, labels, this file. A broken CI +# config is invisible until it is on `main`. +/.github/ @E-SPower/maintainers + +# Front end design tokens and the shared component library: a UI-SPEC violation +# is review feedback, not a nit. +/web/tailwind.config.js @E-SPower/maintainers +/web/src/components/ui/ @E-SPower/maintainers +/web/UI-SPEC.md @E-SPower/maintainers + +# Auth, secrets and the security policy. +/backend/internal/middleware/ @E-SPower/maintainers +/backend/internal/service/auth.go @E-SPower/maintainers +/.github/SECURITY.md @E-SPower/maintainers diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..be8c9210 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,88 @@ +# Contributor Covenant Code of Conduct + +## Our pledge + +We as members, contributors and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive and healthy community. + +## Our standards + +Examples of behaviour that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologising to those affected by our mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behaviour include: + +- The use of sexualised language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behaviour and will take appropriate and fair corrective action in response to any behaviour that they deem inappropriate, threatening, offensive or harmful. + +Community leaders have the right and responsibility to remove, edit or reject comments, commits, code, wiki edits, issues and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing or otherwise unacceptable behaviour may be reported to the community leaders responsible for enforcement: + +- General questions: open an issue on [GitHub Issues](https://github.com/E-SPower/E-SP-Line2/issues); +- Anything private: contact the maintainers through GitHub. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community impact**: use of inappropriate language or other behaviour deemed unprofessional or unwelcome in the community. + +**Consequence**: a private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community impact**: a violation through a single incident or series of actions. + +**Consequence**: a warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary ban + +**Community impact**: a serious violation of community standards, including sustained inappropriate behaviour. + +**Consequence**: a temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent ban + +**Community impact**: demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: a permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][mozilla]. + +For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][faq]. Translations are available at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[mozilla]: https://github.com/mozilla/diversity +[faq]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..e669cf69 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,165 @@ +# Contributing to E-SP-Line2 + +Thanks for wanting to make E-SP-Line2 better. This guide covers setting up a dev environment, the conventions for code and commits, and how to get a change merged. Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) first — it applies to every issue, PR and review. + +## 1. Before you start + +- Search the [open issues](https://github.com/E-SPower/E-SP-Line2/issues) before you file one; a duplicate splits the discussion. +- For anything larger than a bug fix or a small docs patch, open an issue describing the problem and the shape of your fix first. It saves you from building something the project does not want. +- Report security problems privately — see [SECURITY.md](SECURITY.md), not a public issue. + +## 2. Development environment + +| Tool | Version | Purpose | +|---|---|---| +| Go | 1.22+ | build, test and run the backend | +| Node | 20.11+ | build and run the web front end (`web/package.json` `engines`; CI reads it) | +| npm or pnpm | current | front-end dependencies | +| Git | any recent | | + +Component versions matter: `go.mod` and `web/package.json` pin what maintainers and the toolchain use. Do not bump a dependency just because — bump it in its own PR with a reason. + +### Backend + +```bash +git clone https://github.com/E-SPower/E-SP-Line2.git +cd E-SP-Line2 +go mod download +go run main.go # reads ./config/config.yaml, then ./config.yaml, then /etc/e-sp-line2 +``` + +The API listens on `:8080`. Before you expose it beyond localhost, change `jwt.secret` in the config — see [SECURITY.md](SECURITY.md). + +```bash +make build # build to bin/e-sp-line2 +make test # go test ./... — needs CGO_ENABLED=1 and gcc, see below +make fmt # go fmt ./... +make lint # golangci-lint, config in .golangci.yml +``` + +`make lint` is not optional: it is a CI step. The linter is not vendored, so install the pinned version once: + +```bash +go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 +# ~/go/bin must be on PATH +``` + +Backend tests need a C toolchain: `gorm.io/driver/sqlite` is cgo, and with cgo off the driver compiles against a stub that fails at `Open`, so the database tests die with an error that looks like a code defect. Run `export CGO_ENABLED=1` (and install `gcc`) before `make test`. + +### Front end + +```bash +cd web +npm install +npm run dev # vite on :3000, proxying /api and /ws to :8080 +``` + +```bash +npm run build # tsc then vite build +npm run lint # eslint +``` + +Read [web/UI-SPEC.md](../web/UI-SPEC.md) before you touch a page. Every colour comes from a token; every state uses the shared component (`Badge`, `Card`, `Skeleton`, `EmptyState`, `ErrorState`, `PageHeader`, `FormField`). Do not hand-roll `bg-blue-600` into a page, and do not add a dependency without a reason. + +### Database + +GORM `AutoMigrate` creates the schema on startup, so a fresh checkout needs nothing. Hand-written SQL migrations live in `migrations/` with their own [README](../migrations/README.md); note that `main.go` does not currently expose a `migrate` subcommand, so the SQL files are reference material until it does. Add a migration when you change a persisted model, and keep `IF NOT EXISTS` / `ON CONFLICT` so re-runs are safe. + +## 3. Project layout + +The Go module is the repository root (`go.mod`, `main.go`). + +``` +internal/ +├── adapter/ # adapter registry, manager and bridge +├── adapters/ # embedded adapter bundles +├── adaptergateway/ # gateway client for the bridges +├── config/ # configuration loading +├── handler/ # HTTP and WebSocket handlers +├── message/ # event hub, router and dispatcher +├── middleware/ # auth, CORS and logging middleware +├── models/ # GORM models +├── protocol/v3/ # v3 envelope, message chain, signing +├── repository/ # data access +├── server/ # server wiring and routes +└── service/ # business logic +adapters/ # per-platform bridge implementations +cmd/esp-desktop/ # desktop shell +migrations/ # SQL migrations +pkg/logger/ # shared logging helpers +web/src/ +├── api/ # typed API client +├── components/ # layout and UI component library +├── locales/ # zh-CN / en-US strings +└── pages/ # one file per route +docs/ # user and developer guides +``` + +Backend layering is `handler → service → repository`; handlers do not touch GORM directly, and the message layer does not import handlers. New adapters follow the contract in [docs/developer-guide/adapter-development.md](../docs/developer-guide/adapter-development.md). + +## 4. Conventions + +### Code + +- **Go**: [Effective Go](https://go.dev/doc/effective_go) and [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments). Run `make fmt` and `make lint` before pushing — CI runs both, and `make lint` uses `.golangci.yml`. +- **TypeScript/React**: the repo's ESLint config (`web/.eslintrc.cjs`), `npm run lint` must be clean, and `tsc` must pass — `npm run build` runs it. The `--max-warnings` budget in `web/package.json` is a ratchet: a new `any` over it is red, and removing one means lowering the number in the same PR. +- **Comments and user-facing strings in English.** User-facing text goes through i18next; add the key to both `web/src/locales/zh-CN.json` and `en-US.json`, and never delete an existing key. +- Keep error returns wrapped with context (`fmt.Errorf("...: %w", err)`) rather than logged and swallowed. + +### Commits + +[Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): + + + +