Iris/docs/86 - Maintainer - Release Checklist.md

86 - Maintainer — Release Checklist

Manual release procedure. Nothing publishes, tags, or announces automatically by design: every step below is run by a person and verified by eye. Work top to bottom; do not skip the verify gates.

Before starting this publication procedure, complete 87 - Maintainer - Release Readiness.md. It contains the engineering remediation, determinism, performance, CI, and full platform-acceptance gates. This checklist starts only after those gates produce GO or an explicitly accepted GO-WARN decision.

Reference values below assume the current gradle.properties: irisVersion=4.0.0-26.2, minecraftVersion=26.2, fabricLoaderVersion=0.19.3, forgeVersion=26.2-65.0.4, neoForgeVersion=26.2.0.12-beta. For a Minecraft version bump, do 85 - Maintainer - MC Version Bump.md first, then start this checklist.

How to execute this checklist

Use one immutable commit and one JDK 25 environment from preflight through publication. Track build, tests, startup, gameplay, determinism, and publication as separate results; a later pass does not erase an earlier unexplained failure. Stop at the first failed required item, fix it on a new candidate commit, and restart the checklist from preflight.

Publication remains manual. Commands in this document produce local artifacts until the explicit publish section; do not upload, tag, or announce from an unclean or differently tested tree.

a. Preflight

• Working tree clean on the exact commit you intend to tag (git status shows nothing to commit).
• CI is green on that commit. The single verify job (.github/workflows/ci.yml) runs on JDK 25: :core:check, the Bukkit plugin and NMS binding tests, :spi:build, the probe tests plus :probe:run and :probe:deserializationProbe, the shared modded tests on all three loaders, the buildSrc artifact-verifier tests, then verifyBukkitArtifact and verifyModdedArtifacts (which build all four artifacts). Do not release on a red or stale run.
• MasterChangelog.MD Iris section is coherent: one consolidated entry set, deduplicated, no date-sliced headers, and it describes the current shipped state (not superseded intermediate work). The file lives at the workspace root, one level above this repo (../MasterChangelog.MD); the section header is ## Plugin: Iris.
• Version fields correct in gradle.properties: irisVersion is the release version and its trailing -<mc> suffix matches minecraftVersion. For a Minecraft bump, confirm every step in 85 - Maintainer - MC Version Bump.md is done (loader ranges, DataVersion, NMS binding).
• JDK 25 is the active toolchain locally (java -version reports 25).

b. Build

• From the Iris project root: ./build-all.sh. It runs buildAllToOut --no-parallel -PuseLocalVolmLib=false, so local VolmLib substitution is off, the immutable volmLibCoordinate from gradle.properties is used, and the all-platform build is serialized. Each platform task runs its artifact verifier first, so the run either fails or prints a Verified … line per jar plus the === Iris buildAllToOut -> dist/ === summary.
• dist/ contains the four platform jars (exact names for this release):
  • Iris v4.0.0-26.2 [CraftBukkit] 26.1.2-26.2.jar (Bukkit/Paper/Purpur/Spigot/Folia plugin)
  • Iris v4.0.0-26.2 [Fabric] 26.2+0.19.3.jar
  • Iris v4.0.0-26.2 [Forge] 26.2+65.0.4.jar
  • Iris v4.0.0-26.2 [NeoForge] 26.2+26.2.0.12-beta.jar
  • Naming pattern: Iris v<irisVersion> [<Platform>] <target>.jar. For the loader jars <target> is <minecraftVersion>+<loaderDisplay>; for CraftBukkit it is bukkitMinecraftRange (the supported Minecraft range, currently 26.1.2-26.2), not minecraftVersion.
• The SPI jar is built by the same run at spi/build/libs/iris-spi-4.0.0-26.2.jar. It is the adapter/platform contract, not the stable downstream plugin API; it is not copied into dist/ or uploaded to mod portals.
• Each mod jar bundles Iris core, SPI, and Iris-owned shaded libraries. LZ4, OSHI, JNA, and JNA Platform are supplied by the Minecraft 26.2 runtime and must not be bundled or relocated; verifyModdedArtifacts scans outer classes and nested jars for those packages and their relocated forms, so trust its pass rather than re-inspecting by hand.

c. Verify (release gates)

• :core:check and :probe:deserializationProbe passed in CI on the tag commit (a. covers this).
• Golden-hash determinism VERIFY passes on all four platforms and matches the same hash (see 32 - Determinism & Goldenhash.md):
  • Bukkit plugin: /iris developer goldenhash world=<world> radius=<radius> threads=<threads> (mode is hard-wired to AUTO, so it verifies when the matching capture already exists)
  • Fabric mod: /iris goldenhash <radius> <threads> verify
  • Forge mod: /iris goldenhash <radius> <threads> verify
  • NeoForge mod: /iris goldenhash <radius> <threads> verify
  • The modded mode literal comes last, after radius and threads; a bare /iris goldenhash <radius> <threads> runs AUTO instead.
  • The hash is interchangeable across platforms: all four MUST report identical output for the same pack and seed. Any mismatch blocks the release.
• Live modded content-mod gate: on each loader, boot the mod jar alongside a real content mod (e.g. Create) and generate an Iris world. Confirm no load-time rejection, no class-loader crash, and that modded blocks/items/entities author and generate.
  • Fabric + content mod
  • Forge + content mod
  • NeoForge + content mod
• Client-mod matrix: install the mod on the client (keybind H toggles the pregen HUD) and confirm:
  • Modded server + modded client: HUD receives pregen progress over irisworldgen:main.
  • Modded server + vanilla client: server generates normally; vanilla client is unaffected.
  • Paper (Bukkit) server + modded client: HUD receives pregen progress over vanilla plugin messaging.
  • Folia: plugin loads and an Iris world generates on Folia.
  • Non-Iris server + modded client: client is inert, no errors.

Operator-oriented sequences that support these gates: 31 - Operator Runbooks.md. Client channel details: 29 - Client HUD & Protocol.md.

d. Publish (all manual, no automation)

• Modrinth: upload the three mod jars and the plugin jar. Tag loaders fabric / forge / neoforge on the mod files; mark the environment server + client. Game version is 26.2 for the three loader jars; the plugin jar covers the whole bukkitMinecraftRange (26.1.2 and 26.2), so tag both.
• CurseForge: upload the three mod jars with the matching loader tags and game version 26.2.
• Existing plugin distribution channels: publish the plugin jar (Iris v4.0.0-26.2 [CraftBukkit] 26.1.2-26.2.jar) where the plugin already ships.
• Sentry: register the release so incoming reports map to this version (irisVersion is the Sentry release tag). ./gradlew release does this against sentry.volmit.com — it downloads sentry-cli, runs releases new and releases set-commits --auto, and needs SENTRY_AUTH_TOKEN (or -Psentry.auth.token=). It does not finalize the release; do that by hand if needed.
• Storepage staleness review: check the portal listing copy and the storepage/ images for pre-4.0 content (Bukkit-only framing, old feature lists, stale screenshots). Flag anything stale for update before or right after launch. (Review only; this checklist does not change store copy.)

e. Post

• Tag the release commit and push the tag. Existing tags in this repo carry no v prefix and encode the supported MC span (3.9.2-1.20.1-1.21.11), so pick the tag deliberately rather than assuming a format. Archive the already verified dist/ bundle with the release record; no tag-triggered bundle automation is configured.
• Announce the release on the community channels once the portals show the new files live.