mirror of
https://github.com/burrow-dev/burrow-server.git
synced 2026-11-18 17:27:50 -05:00
docs: add CONTRIBUTING.md
Add a contribution guide outlining local setup instructions, testing requirements, security protocols, and development standards for the project.
This commit is contained in:
1 parent
059f059a9e
commit
8afc66de21
1 file changed
+75
@@ -0,0 +1,75 @@
|
||||
# Contributing to Burrow
|
||||
|
||||
Thanks for helping make Burrow safer, kinder, and more reliable. Keep changes small, explain the player-facing effect, and open a pull request against the repository's default branch.
|
||||
|
||||
## Local setup
|
||||
|
||||
Use Node.js 22.5 or later, Git, and an existing checkout containing the tracked client and cached game assets. Install the reviewed runtime dependency with:
|
||||
|
||||
```sh
|
||||
npm ci
|
||||
```
|
||||
|
||||
Run the server with:
|
||||
|
||||
```sh
|
||||
npm start
|
||||
```
|
||||
|
||||
The local web server defaults to `http://127.0.0.1:8080` and the game server to port `9339`. Do not commit `data/`, `cache/`, `.env` files, tokens, recovery-mail credentials, Discord bot tokens, or production exports.
|
||||
|
||||
## Before opening a pull request
|
||||
|
||||
Run the smoke suite and repository invariants from the repository root:
|
||||
|
||||
```sh
|
||||
npm test
|
||||
node .github/scripts/invariants.js
|
||||
```
|
||||
|
||||
Add focused coverage under `test/` when changing a game protocol, permissions, account state, moderation, or web route. Explain any test that cannot run locally and include the exact failure output.
|
||||
|
||||
Use Conventional Commit messages; the pull-request workflow checks them. Keep the change limited to its purpose and describe security implications, especially for authentication, staff permissions, moderation, player data, network input, or media.
|
||||
|
||||
## Security requirements
|
||||
|
||||
Burrow handles account credentials, 2FA, game sessions, player reports, and moderation records. Treat every browser, game, and Discord input as untrusted.
|
||||
|
||||
- Never log, display, or commit passwords, session tokens, recovery links, IP addresses, device identifiers, private keys, or bot tokens.
|
||||
- Do not add web hosts, execute programs from server code, evaluate generated text, or add dependencies without updating and explaining the invariant checks.
|
||||
- `[email protected]` is the only approved runtime dependency. Keep it exactly pinned and update `package-lock.json` in the same pull request when its reviewed version changes.
|
||||
- Preserve permission checks and staff-rank protections. New moderation actions must use the existing role model and leave an audit record.
|
||||
|
||||
The CI security workflow parses all server JavaScript, checks allowed external hosts, scans commits for secrets, and reviews the Flash files that clients load.
|
||||
|
||||
## Discord bot changes
|
||||
|
||||
The optional Discord staff bot is enabled only with `AJ_DISCORD_BOT_TOKEN` and `AJ_DISCORD_GUILD_ID`. It trusts a Discord user only after the user has linked that identity to an active Burrow staff account with 2FA. Do not create an alternate Discord-only permission system.
|
||||
|
||||
All visible bot messages, including errors, status cards, reports, audit logs, and interaction updates, must use Discord Components V2: set `MessageFlags.IsComponentsV2` and use containers/text displays rather than `content` or embeds. Keep player-supplied text safe from mentions and avoid relaying chat, addresses, device data, or tokens to Discord.
|
||||
|
||||
## Server and panel changes
|
||||
|
||||
The server code lives in `lib/`; browser pages live in `public/`; protocol behavior is primarily in `lib/world.js` and the related feature modules. Reuse the panel's shared moderation action path instead of copying bans, warnings, silences, or rank checks into a new surface.
|
||||
|
||||
Document new environment variables in `README.md`. Make optional integrations fail closed or remain disabled when configuration is absent; they must never stop gameplay, moderation records, or account storage when an external service is unavailable.
|
||||
|
||||
## Client and asset changes
|
||||
|
||||
Changes under `swf-src/` require rebuilding the tracked client with Java and JPEXS/FFDec:
|
||||
|
||||
```sh
|
||||
tools/build-client.sh
|
||||
```
|
||||
|
||||
On Windows, run the script through Git Bash or an equivalent POSIX shell. Commit both the source change and the resulting `swf/ajclient.swf` when the client is changed. Do not edit files under `tools/decompiled/` unless the build tool explicitly consumes that source; they are reference output.
|
||||
|
||||
Badge artwork is generated by `tools/make-badges.py`; follow the script's usage notes and commit all generated badge assets together.
|
||||
|
||||
## Pull-request checklist
|
||||
|
||||
- [ ] The change has a clear player, staff, or maintenance outcome.
|
||||
- [ ] Tests and invariants pass, or the exception is explained.
|
||||
- [ ] No secret, personal data, cache, database, or generated local output is included.
|
||||
- [ ] New Discord output uses Components V2 and respects the existing permission/audit model.
|
||||
- [ ] Client source and rebuilt SWF are both included when applicable.
|
||||
Reference in new issue
Block a user