runicgateway.com/CONTRIBUTING.md

Contributing to runicgateway.com

Thanks for your interest. This repository is the public marketing and documentation site for Runic Gateway — the platform that puts a private game server's live state on a public website without ever exposing the game to the internet.

It is a site, not a component. Nothing else in the organisation depends on it, and it depends on everything: almost every sentence here describes something that lives in another repository.

By participating you agree to abide by our Code of Conduct.

Read the plan first

PLAN.md is the design of record. It is not a sketch — it carries the verified platform state, the org lead's fifty-odd decisions, the information architecture, the accuracy machinery and the build phases. A change that contradicts a decision recorded there needs the decision changed first, in the same pull request, with the reasoning written down.

Two things it records are worth knowing before you write a line:

• §1 — the site never re-specifies a contract. docs/ is normative for the protocol, the module API, the backend design and the installer. This site teaches, links out, and quotes versions from data rather than prose. A page that restates a contract is a page that will be wrong later, and nothing will notice.
• §12 — the checks are the mechanism, and their failure is the feature. When the platform moves, this repository goes red so that somebody updates the site. Do not route around a check; if one is wrong, fix the check and say why in the pull request.

Ways to contribute

• Report a bug or request a feature through the issue tracker — templates are provided.
• Improve a page, a check or the build by opening a pull request.
• Never report a security vulnerability in a public issue. See SECURITY.md.

If you spot a claim on the site that is wrong about the platform — a version, a capability, a command that no longer exists — that is the most valuable report this repository can receive.

Development setup

Prerequisites: Node 22 LTS or newer. Nothing else — no database, no game server, no container runtime for ordinary work.

npm install
npm run dev          # http://localhost:4321

npm run build        # → dist/  (prerendered pages + the Node server entry)
npm start            # serve the built site, exactly as the container does

Two directories are bind mounts at runtime and not in the repository: brand/ overrides the stock branding per file, and data/ holds the beta signup store. Both are optional locally; an absent brand/ produces exactly the stock site, and data/ is created on first write.

The checks

There are twelve, plus two test suites. npm run verify runs all of them in dependency order, and that is what CI does on every pull request.

npm run verify

Three of them read other repositories over the Gitea API and need a token with access to the organisation, not just this repository:

GITEA_TOKEN=<token> npm run check:facts       # every version agrees with its authority
GITEA_TOKEN=<token> npm run check:quickstart  # the install page still matches website's own files
GITEA_TOKEN=<token> npm run check:reference   # every name the Reference lists still exists

Without a token they fail rather than skip, deliberately: a check that silently passes when it could not do its job is worse than no check. CI maps the org-level REGISTRY_TOKEN secret into GITEA_TOKEN for those three steps.

The README's "The checks, and why they are not optional" section explains what each one guards. Read it before adding a page — several of them constrain how a page may be written, particularly check:tokens (no colour literal outside src/styles/tokens.css) and check:links (no commit permalinks into org repositories).

Writing for this site

• Understated honesty (D8). The site reads as finished. Where something is not built, the absence is stated as data in src/data/notBuilt.mjs and rendered — never implied by silence and never dressed up as a roadmap.
• No version in prose. Every externally-sourced fact lives in src/data/platform.json and is re-read from its authority by check:facts. If you find yourself typing a version number into a sentence, put it in the data file instead.
• No email address in src/ or scripts/ (D13). The published contact is a brand.json field so that changing it stays a file copy and a restart. check:facts enforces this.
• British spelling, in common with the rest of the organisation's prose.

Branch and pull-request workflow

1. Branch from main with a descriptive name (feature/…, fix/…, docs/…, chore/…).
2. Keep changes focused; small pull requests are easier to review.
3. Run npm run verify before opening the pull request.
4. Push and open a pull request against main. Fill out the template, including the AI-assisted contributions disclosure.
5. A maintainer will review; address feedback with follow-up commits.

Commit messages

Conventional Commits — type(scope): summary, in common with every repository in the organisation. For example fix(docs): correct the installer flag on the quickstart.

What merging does

Merging to main builds a container image, publishes it to the Gitea registry and deploys it (.gitea/workflows/build-image.yml). There is no separate release step and no manual promotion, so a merge is a publication. DEPLOY.md describes the whole path, including how to roll back to a previous build.

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 <noreply@anthropic.com> or Assisted-By: <tool>.
• 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.

Licence

Runic Gateway is licensed under the GNU General Public License v3.0 or later (see LICENSE). 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.