Dont ask

docs/mc-version-bump.md

@@ -0,0 +1,80 @@
+# Minecraft Version Bump Checklist
+
+`gradle.properties` `minecraftVersion` is the single source of truth for the target Minecraft
+version. Most build outputs derive from it. This document lists every edit required to move Iris
+to a new Minecraft version, in order.
+
+## Source of truth
+
+`gradle.properties`:
+
+- `minecraftVersion` — target MC version (e.g. `26.2`). Drives the Bukkit plugin `api-version`,
+  `BuildConstants.MINECRAFT_VERSION`, the `com.mojang:minecraft` coordinate, all mod-metadata
+  minecraft ranges, and every dist/jar artifact name.
+- `fabricLoaderVersion` — Fabric Loader version.
+- `forgeVersion` — Forge version (`<mc>-<forge>`).
+- `neoForgeVersion` — NeoForge version.
+- `irisVersion` — bump the trailing `-<mc>` suffix to match (e.g. `4.0.0-26.2` -> `4.0.0-27.0`).
+
+## Ordered steps
+
+1. Edit `gradle.properties`: update `minecraftVersion`, `fabricLoaderVersion`, `forgeVersion`,
+   `neoForgeVersion`, and the `irisVersion` suffix.
+
+2. Edit `gradle/libs.versions.toml`:
+   - `spigot` — the Spigot/Paper API pin used to compile against (`<mc>-R0.1-SNAPSHOT`).
+   - `fabricApi-*` — the six Fabric API module versions, if the new MC requires different
+     Fabric API builds. Each module is versioned independently (`<version>+<build-hash>`).
+
+3. Edit `core/src/main/java/art/arcane/iris/core/nms/datapack/DataVersion.java` (manual, structural):
+   - Append a new enum constant `V<major>_<minor>("<mc>", <packFormat>, <DataFixer>::new)`.
+   - `packFormat` comes from https://minecraft.wiki/w/Pack_format.
+   - `getLatest()` returns the last enum constant, so append; do not reorder.
+   - Add a matching `IDataFixer` implementation under `core/src/main/java/art/arcane/iris/core/nms/datapack/`
+     if the datapack format changed.
+
+4. Register the new Bukkit NMS binding module:
+   - `settings.gradle` — add `include(':adapters:bukkit:nms:v<major>_<minor>_R<rev>')`.
+   - `build.gradle` — add the binding to the `nmsBindings` map:
+     `v<major>_<minor>_R<rev>: '<spigot-nms-build-version>'` (e.g. `'26.2.build.25-alpha'`).
+   - Create the binding sources under `adapters/bukkit/nms/v<major>_<minor>_R<rev>/`.
+
+5. Update loader version-range metadata (manual floors/ranges only; the `minecraft` ranges are
+   templated from `minecraftVersion` and need no edit):
+   - `adapters/fabric/src/main/resources/fabric.mod.json` — `minecraft` is `~${minecraftVersion}`
+     (auto). Update the `fabricloader` floor (`>=0.19.0`) if the loader minimum changes, and the
+     `jars` list if the bundled Fabric API modules change.
+   - `adapters/forge/src/main/resources/META-INF/mods.toml` — `minecraft` versionRange is
+     `[${minecraftVersion}]` (auto). Update `loaderVersion` (`[64,)`) and the `forge` dependency
+     versionRange for the new Forge line.
+   - `adapters/neoforge/src/main/resources/META-INF/neoforge.mods.toml` — `minecraft` versionRange
+     is `[${minecraftVersion}]` (auto). Update `loaderVersion` and the `neoforge` dependency range
+     if the loader minimum changes.
+
+6. Build and verify:
+   - `./gradlew :core:check`
+   - `./gradlew buildBukkit`
+   - `./gradlew buildFabric`
+   - `./gradlew buildForge`
+   - `./gradlew buildNeoforge`
+
+## Derived automatically (do not hand-edit on a version bump)
+
+- Bukkit plugin `api-version` — `adapters/bukkit/plugin/build.gradle` reads `minecraftVersion`.
+- `BuildConstants.MINECRAFT_VERSION` — stamped by the `generateTemplates` task in
+  `core/build.gradle` from `minecraftVersion`; consumed by `Tasks.supportedVersions`.
+- Mod-metadata `minecraft` version ranges — templated from `minecraftVersion` at `processResources`.
+- Dist/jar artifact names and the `com.mojang:minecraft` coordinate — composed from
+  `minecraftVersion` in the build scripts.
+
+## Notes
+
+- `build.gradle`, the adapter `build.gradle` files, and `settings.gradle` carry `.getOrElse('26.2')`
+  defensive defaults for the version properties. `gradle.properties` always overrides them, so a
+  bump does not require touching those fallbacks; refresh them only if the checked-in default should
+  track the current release.
+- The Java literal `"26.2"` intentionally remains in `DataVersion.java` (structural enum constant),
+  `core/src/test/java/art/arcane/iris/core/nms/MinecraftVersionTest.java`, and
+  `core/src/test/java/art/arcane/iris/core/lifecycle/PaperLibBootstrapTest.java`. The test files use
+  MC version strings as parser fixtures, not as a version source; update them only when the version
+  string formats they exercise change.

docs/release-checklist.md

@@ -0,0 +1,78 @@
+# Iris Release Checklist
+
+Manual release procedure. There is no release automation by design: every step below is run by
+a person and verified by eye. Work top to bottom; do not skip the verify gates.
+
+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.0`,
+`neoForgeVersion=26.2.0.6-beta`. For a Minecraft version bump, do `docs/mc-version-bump.md` first,
+then start this checklist.
+
+## 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 `verify` job (`.github/workflows/ci.yml`) runs
+      `./gradlew :core:check :spi:build :probe:deserializationProbe` on JDK 25; the `build-artifacts`
+      matrix builds all four platform jars. 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).
+- [ ] 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
+      `docs/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: `./gradlew buildAll`
+- [ ] `dist/` contains the four platform jars (exact names for this release):
+  - [ ] `Iris v4.0.0-26.2 [CraftBukkit] 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.0.jar`
+  - [ ] `Iris v4.0.0-26.2 [NeoForge] 26.2+26.2.0.6-beta.jar`
+  - Naming pattern: `Iris v<irisVersion> [<Platform>] <mc>[+<loaderDisplay>].jar`.
+- [ ] The developer SPI jar is built by the same run at `spi/build/libs/iris-spi-4.0.0-26.2.jar`.
+      It is the platform-API artifact for downstream developers and is not copied into `dist/`; it is
+      not uploaded to the mod portals (see publish).
+- [ ] Each mod jar bundles core + spi + shaded libs; each plugin/mod jar is self-contained.
+
+## 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:
+  - [ ] Bukkit plugin: `/iris goldenhash verify <radius> <threads>`
+  - [ ] Fabric mod: `/iris goldenhash verify <radius> <threads>`
+  - [ ] Forge mod: `/iris goldenhash verify <radius> <threads>`
+  - [ ] NeoForge mod: `/iris goldenhash verify <radius> <threads>`
+  - 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 smoke: plugin loads and an Iris world generates on Folia.
+  - [ ] Non-Iris server + modded client: client is inert, no errors.
+
+## 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; set game version 26.2.
+- [ ] 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.2.jar`) where the plugin already ships.
+- [ ] Sentry: add a release note / mark the release so incoming reports map to this version
+      (the mod version string is the Sentry release tag).
+- [ ] Storepage / `listing.json` staleness review: check the listing copy for pre-4.0 content
+      (Bukkit-only framing, old feature lists, 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 (`v<irisVersion>`) and push the tag. The `release-bundle` CI job
+      (tag-gated, `refs/tags/v*`) runs `buildAll` and uploads the `dist/` bundle for the record.
+- [ ] Announce the release on the community channels once the portals show the new files live.