Validation and releases

Automated checksCopy Anchor Link

Each project's build runs its check, so these gates are enforced by a normal build:

For how to run these locally, see common builds and tests.

Test reportsCopy Anchor Link

What to run for a changeCopy Anchor Link

• For documentation-only changes, checking the content, commands, links and git diff --check is enough; there is no need to rerun unrelated audio tests.
• When fixing a bug, prefer regression evidence that fails before the fix and passes after it. Do not add tests that merely restate the implementation.
• When synthetic audio tests pass but real audio is wrong, check device routing, capture/playback settings and do a real two-player test; synthetic tests do not cover every acoustic condition (see audio validation).

There is no CICopy Anchor Link

Nothing in this repository runs automatically: there are no GitHub Actions workflows and no CI server. Every check and every release is a script in scripts/, run from a laptop, which is also why there is no "CI-only" step that can drift away from what you run locally.

You need JDK 21 and 25, Python 3.9+ and git; publishing additionally needs the GitHub CLI authenticated, and the Discord webhook in scripts/.env (verification needs no credentials at all). The matrix must run serially in one working tree — Loom, ModDevGradle and ForgeGradle share per-version state — so do not run two of them at once.

Because the matrix is read from the version catalog, adding a Minecraft version does not require editing any build script.

Commit and reviewCopy Anchor Link

Commits follow Conventional Commits, e.g. feat(client): add device selection, fix(audio): preserve speech endings, docs: document development workflow. The subject focuses on the purpose; unrelated features, resource updates or cleanups go into separate commits. Breaking changes and rollbacks should include the reason and compatibility notes.

Before committing, check git status, git diff, git diff --cached and git diff --check. Commit only files related to the current requirement; never commit build/, .gradle/, IDE settings, game run data, credentials or real authentication details.

A PR description should include the problem and result, the affected modules/Minecraft versions, the test commands and their results, and any in-game acceptance still outstanding; protocol or config changes also describe mixed-version behaviour and rollback.

PublishingCopy Anchor Link

Releasing with release.pyCopy Anchor Link

python3 scripts/release.py does a whole release from one command, asking only what it has to, with arrow keys:

1. Checks that the tree is clean, on main, in step with origin (and offers to fast-forward), and that the GitHub CLI, the Discord webhook and the Modrinth token are all there.
2. Asks what to publish: a dev build, a stable release, or plan only, which shows everything a release would do and does none of it.
3. Works out the versions. A stable release proposes the next version from the commits since the last one — a breaking change (feat!: or BREAKING CHANGE) is minor before 1.0 and major after, a feature minor after 1.0, anything else a patch. Client, server and proxy move together; an addon (cinema.version) moves only if its own code changed. A dev build of a version that is already released moves to the next patch first, since 0.2.1-dev.12 would sort below 0.2.1 and nobody on the dev channel would be offered it.
4. Writes the release notes from those commits, grouped into New, Fixes, Performance and Changes, with a compare link — used for GitHub, Discord and Modrinth. Keep them, edit them in $EDITOR, or write your own.
5. Steps to include: quick tests before the long build, the GitHub release, Modrinth (stable only), Discord, and — after a stable release — moving the catalog on to the next version, so dev builds keep sorting above it.
6. Runs it, with every step live on screen and the last lines of Gradle's output under the one running. The version bump is only committed once the build has succeeded; a failed build puts the catalog back. The full output goes to build/release-logs/.

If a run stops partway — a failed upload, a closed laptop — running it again offers to resume, skipping every step that already finished.

--channel dev|release skips the first question, --yes takes every default without asking, and --plan only shows the plan. Standard library only: there is nothing to install.

Before a releaseCopy Anchor Link

ArtifactsCopy Anchor Link

Modrinth release scriptCopy Anchor Link

Publishing to Modrinth uses scripts/modrinth_release.py (Python 3, standard library only). It builds and publishes every client loader, every server loader, the Paper plugin and the proxy plugin, each as its own Modrinth version whose version number carries its side.

# Show the release plan; builds and uploads nothing (no token needed)
python3 scripts/modrinth_release.py --dry-run

# Build everything and publish versions that do not exist yet
python3 scripts/modrinth_release.py --changelog-file CHANGELOG.md

# Only NeoForge clients for 26.2, reusing jars already built
python3 scripts/modrinth_release.py --side client --loaders neoforge --minecraft 26.2 --skip-build

How it behaves:

• Token: MODRINTH_TOKEN in scripts/.env (gitignored) or the environment; required for everything except --dry-run.
• Configuration: scripts/modrinth.json holds the project id and slug, the version name prefix, and the loader tags and dependencies per side and loader.
• Building: unless --skip-build, client/server mods are built through build_matrix.py for the selected versions and loaders, and Paper/proxy with :server:paper:build and buildAllProxy.
• Skipping existing versions: a Modrinth version with the same version number is skipped by default, so re-running after bumping only one side's version publishes only that side.
• Beta loaders: artifacts built against a beta loader (a NeoForge version containing -beta) are published as beta automatically.
• Version number limit: Modrinth limits version numbers to 32 characters from a restricted character set; the script stops before uploading if a number breaks that, in which case shorten the side version in gradle/socketsvc.properties.

What each side is published with (from scripts/modrinth.json and the script):

Store listingCopy Anchor Link

The Modrinth project page text lives in the Modrinth listing, beside the release script: a short description (under the Short Desc marker) and the long description (under Long Desc), covering why WebSocket instead of UDP, voice chat features, the spatial speaker API, requirements, installation, server configuration highlights and servers using SocketSVC. The release script only creates versions and does not update the project description, so edits to it have to be applied to the Modrinth project page separately. Keep it consistent with the overview when features or requirements change.

RollbackCopy Anchor Link

• Roll back to a known-good artifact and keep player settings.
• For source rollback, prefer a revert with a stated reason; avoid rewriting shared branch history.
• When withdrawing support for a Minecraft version, update supported and adjust default if needed (see withdrawing a version or loader).
• Verify protocol rollbacks using the mixed-version mechanism described in the voice protocol.