# Contributing to Runic Gateway — Integration Kit Thanks for your interest! This repo is the **Integration Kit**: the instruction book for putting a game that is not Ultima Online onto a Runic Gateway site, plus a `template/` module that builds. It is the only repo in this project written for someone **outside** the organisation, and that changes what a contribution looks like here. Elsewhere the docs record decisions; here they teach a stranger. The most valuable contribution is not a correction — it is a report of the place you got stuck and what you did next. By participating you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). ## Status: draft The kit's acceptance test is that **someone outside this project builds a working module for a new game by following it alone, without reading core's source.** Until that has happened it is a draft however finished it looks, and the README says so on the front page. Do not remove that banner in a PR that is not the one recording a passed acceptance run. ## The rule that governs every change here **The kit never re-specifies a contract.** These are normative; the kit teaches and links out: - [`MODULE_API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md) — everything a module may do. - [`MODULE_SYSTEM.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_SYSTEM.md) — why the system is shaped this way, and the install model. - [`link/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/PLAN.md) and [`INTEGRATION.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/link/INTEGRATION.md) — the game↔sidecar wire protocol. So: **do not copy a member list, a field table or a set of rules into a chapter.** Quote the part you are explaining, with a link, and let the reader go to the authority for the whole. A guide that restates a contract diverges from it silently, and the reader who follows the divergent copy gets a module that fails validation for reasons the guide cannot explain. If a rule looks *wrong* rather than badly explained, that is a docs-repo PR against `MODULE_API.md`, not a change here. The kit does not get to disagree with the contract in prose. ## Ways to contribute - **Report where the kit failed you** through the [issue tracker](https://gitea.whitlocktech.com/RunicGateway/Integration-kit/issues) — templates provided. "I could not work out how to X" is a bug in this repo. - **Fix or extend a chapter**, or the template, with a pull request. - **Never** report a security vulnerability in a public issue — see [SECURITY.md](SECURITY.md). ## Working on this repo **Prerequisites:** Node 20+, and a checkout of [`RunicGateway/website`](https://gitea.whitlocktech.com/RunicGateway/website) if you are touching `template/` — a module is not runnable on its own. ```bash node scripts/checkLinks.js # every relative link resolves; no commit permalinks ``` The template's own checks live under `template/` and are described in the chapter that introduces it. ### What CI checks, and why it is shaped that way `.gitea/workflows/pr-checks.yml` clones core at a **pinned commit** and then: 1. asserts the version `template/module.json` declares still **equals** that core's `MODULE_API_VERSION`; 2. builds the template and runs its boundary guards; 3. runs the link check over every markdown file. Check 1 is the anti-rot mechanism. A contract bump in core changes that number, this repo goes red, and someone has to look at whether a chapter has become untrue — which is the half a machine cannot check. That is also why a `MODULE_API_VERSION` bump in core carries an obligation to pass over this kit in the same PR ([`MODULE_SYSTEM.md` §2.10](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_SYSTEM.md)). **The pin points at a commit on core's `edge` branch, not `main`.** The module system has not cut over yet; `main` has no `server/src/modules/` at all. Moving the pin is a deliberate, reviewed change — it is the moment someone re-reads the chapters — so it is a line in the workflow rather than a floating branch name. ### Prose conventions - **Second person, present tense.** "You register a route", not "the module author registers a route". - **Say why before how.** Every rule in this project exists because something broke; a rule without its reason is one the reader will route around. - **Examples are quotations.** Code blocks come from `template/` or from a real repo, with a path next to them. An invented example is one nobody has compiled. - **Own the mistakes.** Where this project got something wrong and paid for it, the kit says so plainly. That is the part a reader cannot get anywhere else. - One sentence per line is not required, but keep lines under ~100 characters. ### Commit messages [Conventional Commits](https://www.conventionalcommits.org/) — `type(scope): summary`. `docs:` for chapters, `feat:`/`fix:` for the template, `ci:` for workflows. ## Branch & PR workflow 1. Branch from `main` (`feature/…`, `fix/…`, `docs/…`, `chore/…`). 2. Keep it focused. 3. Open a pull request against `main` and fill in the template, including the **AI-assisted contributions** disclosure. 4. A maintainer reviews; address feedback with follow-up commits. This repo develops on its own `main` from its first commit — no `edge`, no cutover. ## AI-assisted contributions (disclosure required) This project is developed openly with AI assistance, and we ask the same transparency of everyone. **If you used an AI tool** (Claude, Copilot, ChatGPT, Cursor, etc.) to help produce a contribution, you must disclose it: - Tick the AI-usage box in the pull-request template and name the tool(s). - Mark AI-authored commits with a trailer, e.g. `Co-Authored-By: Claude ` or `Assisted-By: `. - You remain responsible for every line you submit: review it, understand it, and make sure it is correct and that you have the right to contribute it. Disclosed AI assistance is welcome. Undisclosed AI-generated contributions are not, and may be closed. ## License Runic Gateway is licensed under the **GNU General Public License v3.0 or later** (see [LICENSE.md](LICENSE.md)). By submitting a contribution you agree that it is licensed under the same terms (inbound = outbound) and that you have the right to contribute it.