Contributing

Ground rulesCopy Anchor Link

• Open an issue before a large change.
• Settle the design in an issue first for a new dependency, a change to the process or deployment model, the node channel protocol, NodeConfig IR semantics, or the security baseline.
• Report security vulnerabilities privately as described in SECURITY.en.md, not in a public issue.
• Pull requests that break the principles below are not merged.

Development environmentCopy Anchor Link

End-to-end tests also need curl, jq, goreleaser v2, syft, cosign v3.1.3, a checkout of edgeweir-node next to this repository (or EDGEWEIR_NODE_CONTEXT) whose out/openresty holds the edgeweir-openresty packages for the Docker architecture (make openresty-packages; scripts/e2e.sh builds them first when missing, which needs Docker Buildx), a node image from before G3, edgeweir-node:pre-g3 (scripts/e2e-g3.mjs builds it from edgeweir-node commit 6da3403 when missing), and network access to deb.debian.org and openresty.org (building the node image or the edgeweir-openresty packages for the first time also needs github.com, download.gnome.org and vault.almalinux.org). The Playwright steps need Chromium:

pnpm --filter @edgeweir/console exec playwright install chromium

Local runCopy Anchor Link

1. Install dependencies.

   Copy Text

   pnpm install

2. Start local PostgreSQL 18. It listens on 127.0.0.1:5432 (change the port with DEV_POSTGRES_PORT); user, password, and database are all edgeweir.

   Copy Text

   docker compose -f compose.dev.yml up -d

3. Create .env and set EDGEWEIR_MASTER_KEY to the output of openssl rand, unchanged. DATABASE_URL in .env.example matches compose.dev.yml.

   Copy Text

   cp .env.example .env
   openssl rand -base64 32

4. Start the console.

   Copy Text

   pnpm dev

   One process: :3000 serves the UI and API (the front end uses Vite HMR), :8443 serves the node channel. Server changes restart the whole process. Until setup completes, the startup log prints the setup token (setupToken field).

5. Verify.

   Copy Text

   curl -s http://localhost:3000/healthz

   Expected output: {"status":"ok","version":"dev"}. Open http://localhost:3000/setup and enter the setup token to complete the setup wizard.

CommandsCopy Anchor Link

CI runs on pull requests and pushes to master: pnpm lint, no diff in packages/proto after pnpm proto:gen, pnpm typecheck, pnpm test, pnpm build, go vet and go test -race for helpers/certd, the image build, and the end-to-end tests.

TestsCopy Anchor Link

Run a single Vitest file from apps/console:

pnpm exec vitest run test/server/docs.test.ts

Tests enforce these conventions:

Every new API procedure has a Vitest case.

End-to-end testsCopy Anchor Link

1. Build and start the test stack (postgres, console, node, test origins, and test clients).

   Copy Text

   docker compose -f compose.e2e.yml up -d --build

2. Run the tests. --up starts the stack first; --down removes the stack and its volumes afterwards; --skip-ui skips Playwright.

   Copy Text

   pnpm e2e

3. Verify: the output ends with E2E OK.

The variables for a second, parallel stack (COMPOSE_PROJECT_NAME, E2E_CONSOLE_PORT, E2E_NODE_PORT, E2E_TAG, E2E_SUBNET, E2E_ISOLATED_SUBNET, E2E_INSTALL_IMAGE, EDGEWEIR_NODE_CONTEXT) are listed in README end-to-end tests.

Commit conventionsCopy Anchor Link

Use Conventional Commits.

<type>(<scope>): <subject>

<body>

<footer>

Scopes: console, web, api, db, contract, compiler, proto, node-channel, certd, deploy, e2e, doc. Omit the scope for changes that span several modules.

Examples:

feat(deploy): add deploy.sh to install and upgrade 宝塔 / aaPanel compose deployments
fix(certd): renew without ARI replaces when the CA rejects the new order
feat(console)!: drop the public landing page from the open core

Code conventionsCopy Anchor Link

UI rulesCopy Anchor Link

InternationalizationCopy Anchor Link

• Every UI string goes through a Paraglide message function. Message files: apps/console/messages/zh-CN.json (default locale) and apps/console/messages/en.json.
• Keys are snake_case and start with the page or feature, e.g., nav_sites, cert_brotli_unavailable.
• Both locales change together: same key set, same placeholders, no empty values.
• English counts use plural variants of the inlang message format (local countPlural = count: plural, one match entry per plural category, every variant with the same placeholders); zh-CN keeps a plain string.
• src/web/routes and src/web/components contain no Chinese literals and no English UI text, including aria-*, title, alt, and placeholder.
• The server does not build user-facing sentences: the API returns error codes and the UI translates them; unknown codes fall back to the server's English message.

Error codesCopy Anchor Link

1. Add the code to errorDefs in packages/contract/src/errors.ts with its HTTP status and params.
2. On the server, call fail(CODE, message, data) (apps/console/src/server/lib/errors.ts): message is the English fallback, data supplies the fields named in params.
3. Add the message to both message files, with placeholders matching params.

API and server conventionsCopy Anchor Link

Proto changesCopy Anchor Link

proto/ is the only contract between the console and edgeweir-node.

1. Edit the .proto files under proto/. Within the edgeweir.node.v1 package, only backward-compatible additions; a breaking change needs a new v2 package. NodeConfig follows canonical-encoding constraints: no map fields, fields declared in ascending field-number order.

2. Run the linter.

   Copy Text

   pnpm proto:lint

3. Compare against the previous proto tag to confirm there is no breaking change.

   Copy Text

   pnpm exec buf breaking proto --against '.git#tag=proto/vX.Y.Z,subdir=proto'

4. Generate TypeScript and commit the proto/ change together with the generated code in packages/proto. CI checks that the generated code matches proto/.

   Copy Text

   pnpm proto:gen

5. After the merge to master, a maintainer tags proto/vX.Y.Z: new fields or RPCs bump the minor version, comment-only changes bump the patch version.

6. In edgeweir-node, set PROTO_TAG in the Makefile to the new tag, regenerate the Go code, adapt the node, and commit internal/gen/.

   Copy Text

   make proto

7. Release order: upgrade the console first, then the nodes. The console stays compatible with nodes on the previous proto version.

Database schema changesCopy Anchor Link

1. Edit packages/db/src/schema.

2. Generate the migration.

   Copy Text

   pnpm db:generate

3. Commit the new SQL file and meta/ snapshot in packages/db/migrations together with the schema change.

4. List the new migration file name and any new table names in the data model section of ARCHITECTURE.md.

5. Verify.

   Copy Text

   pnpm test

The console runs database migrations at startup.

Environment variablesCopy Anchor Link

1. Declare the variable in the schema in apps/console/src/server/lib/env.ts (zod validation and default).

2. Add it to .env.example with a comment stating its purpose and default. Variables interpolated by the compose files also go into .env.example.

3. Describe the variable in both language versions of the environment variables reference.

4. Verify.

   Copy Text

   pnpm test

Operator configuration belongs in System; environment variables keep only values needed before setup or at the infrastructure level. When a setting exists both in system settings and as an environment variable, precedence is: value saved in System, environment variable, default.

Updating pinned images and actionsCopy Anchor Link

Third-party inputs are pinned by immutable references; pnpm test rejects unpinned references, and edgeweir-node runs the same check with make pin-check. Images built from this repository or edgeweir-node are referenced by tag.

1. Look up the image digest. The Digest in the output is the multi-arch index digest; do not use a single-platform digest.

   Copy Text

   docker buildx imagetools inspect <image>:<tag>

2. Look up the commit for an action release. For an annotated tag, use the SHA on the line ending in ^{}.

   Copy Text

   git ls-remote --tags https://github.com/<owner>/<action>

3. Change the tag and digest (or the SHA and version comment) together.

4. After changing compose.baota.yml or compose.baota-host.yml, copy the full file into the embedded template in deploy.sh; keep PG_IMAGE in deploy.sh equal to the PostgreSQL image in compose.baota.yml.

5. Verify.

   Copy Text

   pnpm test
   bash deploy.sh template bundled | diff - compose.baota.yml
   bash deploy.sh template host | diff - compose.baota-host.yml

After a base image update, run the Release workflow manually in Actions to rebuild the tip of master.

ReleasesCopy Anchor Link

Version pinning, upgrades, and rollback: Versions, upgrades, and rollback. Artifact signatures and verification: SECURITY.en.md.

DocumentationCopy Anchor Link

• Published docs are plain GitHub Markdown: name.md (Simplified Chinese, default) and name.en.md (English, same sections as name.md).
• The documentation site lives in doc/ (Fumadocs, Next.js static export) as its own pnpm workspace (doc/pnpm-workspace.yaml, doc/pnpm-lock.yaml). .github/workflows/docs.yml builds the site on pull requests and publishes it to GitHub Pages on pushes to master: https://marvinli001.github.io/edgeweir/.
• doc/scripts/sync-content.mjs holds the page map (SECTIONS) and converts the Markdown. A new page must be added to the page map.

Pull request checklistCopy Anchor Link

• One topic per pull request; the description states the motivation, the changes, and how they were verified, and links the issue.
• pnpm lint, pnpm typecheck, and pnpm test pass; pnpm build and pnpm e2e run as listed in Commands.
• Commits follow the commit conventions.
• UI copy is updated in both zh-CN and en; new error codes have messages.
• Schema changes include the migration SQL, the snapshot, and the ARCHITECTURE.md data model update.
• New environment variables are in env.ts, .env.example, and the environment variables reference.
• Management actions write the audit log.
• UI changes include screenshots.
• Behavior changes are reflected in the Chinese and English docs (README, deployment docs).
• No test was skipped, deleted, or weakened.

LicenseCopy Anchor Link

Edgeweir is released under AGPL-3.0-only. Submitting a contribution licenses it under AGPL-3.0-only and confirms the right to do so.

The open core permits compliant commercial use. The open-source edition serves a single operator; multi-tenancy (organizations, members, roles, and isolation), the customer-facing portal, plans and billing, finance, and reselling belong to a separate commercial operations product (LICENSING.en.md). Contributing to the core does not automatically grant the project a right to relicense under proprietary terms; a dual license or a plugin linking exception requires separate verification of code ownership and contributor authorization.