Skip to main content

​
Language and style

  • English only — code, comments, commits, docs.
  • Framework code (everything outside Gatherer/) is structured with ---@ annotations and volvox.* namespacing — match it.
  • Gatherer core files are predominantly globals, mixed indentation, and terse names (scan, avoid, Fishi, Spore). Copy the indentation character and block style of the nearest enclosing function in the same file. Do not reformat existing lines.
  • New Gatherer-internal helpers are named Gatherer<Thing>.

​
Commits

Use Conventional Commits with a scope: 
feat(gatherer): add underground node retry TTL
refactor(framework): resolve file API through ResolveApiFunction
docs: document the state machine

​
Changelog

CHANGELOG.md follows Keep a Changelog 1.1.0 and is updated for every change. Entries stay under ## [Unreleased] until a release is explicitly cut, using the standard categories: Added, Changed, Deprecated, Removed, Fixed, Security. Every released version uses the heading ## [X.Y.Z] — Release Name - YYYY-MM-DD. Choose a short, unique gathering pun tied to the release’s standout theme.

​
Releases

Releases are cut with scripts/changelog-release.sh:
1

Determine the bump level

Scan [Unreleased] entries: any BREAKING: / [breaking] → major; else any ### Added entries → minor; else → patch. An explicitly requested level or version wins.
2

Choose a release name

Pick a short, unique gathering pun tied to the release’s standout theme.
3

Run the script

scripts/changelog-release.sh [level-or-version] [YYYY-MM-DD] "Release Name"
For example:
scripts/changelog-release.sh auto 2026-08-01 "Mulch Ado About Nothing"
The script requires a nonblank, single-line name. Maintainers are responsible for following the short, unique gathering-pun convention.
4

Confirm

Verify the version, release name, and date in the canonical ## [X.Y.Z] — Release Name - YYYY-MM-DD heading in CHANGELOG.md before committing.

​
Verification checklist

Since there is no runtime harness, every change must:
  1. Pass the static tooling: selene . && stylua --check . && biome check .
  2. Not break the load order (loadorder.json) — a file may only reference symbols defined by files above it.
  3. Preserve volvox.* contracts.
  4. For logic changes: identify the specific in-game trigger (bot state, object type, or user action) and the observable outcome (log message, state transition) that confirms the change works.