Contributing

Contributing

Rules

• No backwards compatibility. Target the current Paper version and toolchain only. No version adapters, legacy branches, deprecated paths, or compat packages. Older 1.21 clients connect through ViaVersion and ViaBackwards.
• No code comments. Use precise names instead. The only exception is vistructum-api: every public and protected type and member needs Javadoc, and the build fails without it (-Xdoclint:all/protected -Werror). Line and block comments stay forbidden there too.
• Stateless. Decisions depend only on explicit inputs and on SQLite. Do not add long-lived in-memory state. Buffers only transport data and never decide anything.
• Docker. Every runnable component has its own Dockerfile, and docker compose build must pass on a fresh checkout.
• Code and identifiers are in English.

Checks

Every pull request runs .github/workflows/build.yml:

Job	Runs
java	mvn package with all tests
ml	ruff check, pytest, and a small train and export smoke test
docker	docker compose build

Run the same checks locally before you push:

mvn package
cd ml && ruff check --line-length 120 . && PYTHONPATH=$PWD:$PWD/train python -m pytest -q tests train/tests
docker compose build

Changing a model

1. Replace the file in models/.
2. Regenerate the parity fixtures, which keep Java and Python inference identical:

   PYTHONPATH=$PWD/ml:$PWD/ml/train python3 ml/parity.py

3. Commit the model and the fixtures together.

After the merge, .github/workflows/models.yml publishes a models-<sha> release. Servers with models.update: auto pick it up within models.check-hours.