From 8afc66de2119a7d840c630c4fa0f0414e4f90b46 Mon Sep 17 00:00:00 2001 From: Snipzil Date: Tue, 20 Oct 2026 20:35:20 -0400 Subject: [PATCH] docs: add CONTRIBUTING.md Add a contribution guide outlining local setup instructions, testing requirements, security protocols, and development standards for the project. --- CONTRIBUTING.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6c8846b --- /dev/null +++ b/CONTRIBUTING.md @@ -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. +- `discord.js@14.26.4` 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.