mirror of
https://github.com/VolmitSoftware/Iris.git
synced 2026-08-30 05:50:48 +00:00
d
This commit is contained in:
Brian Neumann-Fopiano
@@ -4,7 +4,7 @@
|
||||
|
||||
## How to run the bump
|
||||
|
||||
Use a dedicated branch or worktree and begin from a green build. Record the old and new Minecraft, Bukkit API, loader, datapack-format, and NMS binding values before editing. Complete the ordered steps without skipping ahead, run the focused gate after each platform boundary, then run the full all-platform build and disposable-server lifecycle smokes.
|
||||
Use a dedicated branch or worktree and begin from a green build. Record the old and new Minecraft, Bukkit API, loader, datapack-format, and NMS binding values before editing. Complete the ordered steps without skipping ahead, run the focused check after each platform boundary, then run the full all-platform build and the disposable-server lifecycle runbooks.
|
||||
|
||||
Stop when an upstream API, mapping, or loader artifact is unavailable; do not hide the gap behind a legacy fallback. The bump is complete only when generated artifact names, metadata ranges, data fixers, NMS selection, tests, and documentation all agree on the same target.
|
||||
|
||||
@@ -12,7 +12,7 @@ Stop when an upstream API, mapping, or loader artifact is unavailable; do not hi
|
||||
|
||||
`gradle.properties`:
|
||||
|
||||
- `minecraftVersion` — target MC version (e.g. `26.2`). Drives `BuildConstants.MINECRAFT_VERSION`, the `com.mojang:minecraft` coordinate, all mod-metadata minecraft ranges, and every dist/jar artifact name.
|
||||
- `minecraftVersion` — target MC version (e.g. `26.2`). Drives `BuildConstants.MINECRAFT_VERSION`, the `com.mojang:minecraft` coordinate, all mod-metadata minecraft ranges, and the three loader jar names. The CraftBukkit jar name comes from `bukkitMinecraftRange` instead (step 1).
|
||||
- `apiVersion` — Bukkit plugin `api-version` (e.g. `26.1`). Deliberately decoupled from `minecraftVersion`: it is the lowest Minecraft release line the single plugin artifact loads on (currently `26.1` so one jar serves 26.1.2 and 26.2). Bump it only when dropping support for the older line.
|
||||
- `fabricLoaderVersion` — Fabric Loader version.
|
||||
- `forgeVersion` — Forge version (`<mc>-<forge>`).
|
||||
@@ -21,27 +21,31 @@ Stop when an upstream API, mapping, or loader artifact is unavailable; do not hi
|
||||
|
||||
## Ordered steps
|
||||
|
||||
1. Edit `gradle.properties`: update `minecraftVersion`, `fabricLoaderVersion`, `forgeVersion`, `neoForgeVersion`, and the `irisVersion` suffix. Revisit `apiVersion` only if the bump drops support for the oldest Minecraft line the plugin artifact still loads on.
|
||||
1. Edit `gradle.properties`: update `minecraftVersion`, `fabricLoaderVersion`, `forgeVersion`, `neoForgeVersion`, and the `irisVersion` suffix. Revisit `apiVersion` only if the bump drops support for the oldest Minecraft line the plugin artifact still loads on. `bukkitMinecraftRange` is deliberately absent from `gradle.properties`; it defaults to `'26.1.2-26.2'` in `build.gradle` and is the version string the CraftBukkit jar filename carries, so edit that default (or pass `-PbukkitMinecraftRange=`) whenever the supported Bukkit range moves.
|
||||
|
||||
2. Edit `gradle/libs.versions.toml`:
|
||||
- `spigot` — the Spigot/Paper API pin used to compile against (`<mc>-R0.1-SNAPSHOT`).
|
||||
- `paper-api` — the compile pin for `:core` and `:adapters:bukkit:plugin` (currently `26.1.2.build.74-stable`). Like `apiVersion`, it is held at the lowest supported release line so one plugin jar loads across the whole range; raise it only when dropping that line.
|
||||
- `spigot` — the Spigot API pin (`<mc>-R0.1-SNAPSHOT`). Used `compileOnly` by the three modded adapters and `:probe` only, never by the Bukkit plugin. Bump it with `minecraftVersion`.
|
||||
- `fabricApi-*` — the ten Fabric API module versions, if the new MC requires different Fabric API builds. Each module is versioned independently (`<version>+<build-hash>`). The ten are `base`, `registrySync`, `resourceLoader`, `lifecycleEvents`, `commandApi`, `eventsInteraction`, `networking`, `rendering`, `keyMapping`, `permission`. Every one of them is bundled jar-in-jar and must be declared in `fabric.mod.json` `jars` — see step 7.
|
||||
|
||||
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)`.
|
||||
- Append a new enum constant named for the MC version with dots replaced by underscores: `V<mc>("<mc>", <packFormat>, <DataFixer>::new)`. The current tail is `V26_1_2("26.1.2", 101, DataFixerV1217::new), V26_2("26.2", 107, DataFixerV1217::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.
|
||||
- `getLatest()` returns the last enum constant, so append at the end; do not reorder, and leave `UNSUPPORTED` first.
|
||||
- Reuse the existing fixer when the datapack format did not change (26.1.2 and 26.2 both use `DataFixerV1217`). If it did change, add a new `IDataFixer` implementation in a versioned subpackage under `core/src/main/java/art/arcane/iris/core/nms/datapack/` (existing ones are `v1192`, `v1206`, `v1213`, `v1217`).
|
||||
|
||||
4. Register the new Bukkit NMS binding module:
|
||||
4. Register **and** select the new Bukkit NMS binding. The revision tag is spelled out by hand in five places plus the sources; miss any one and the build fails or the plugin refuses to bind at boot.
|
||||
- `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>/`.
|
||||
- `build.gradle` — add the binding to the `nmsBindings` map: `v<major>_<minor>_R<rev>: '<paper-dev-bundle-version>'`. That value is passed to paperweight's `paperDevBundle(...)`, not to Spigot BuildTools; it is currently `'26.1.2.build.74-stable'`, held at the same low pin as `paper-api`.
|
||||
- `build.gradle` — update `art/arcane/iris/core/nms/v26_2_R1/NMSBinding.class` in `requiredBukkitArtifactEntries` to the new tag, or `verifyBukkitArtifact` fails against the shipped jar.
|
||||
- `.github/workflows/ci.yml` — update the hardcoded `:adapters:bukkit:nms:v26_2_R1:test` task path in the `verify` job.
|
||||
- `core/src/main/java/art/arcane/iris/core/nms/NmsBindingSelector.java` — the runtime half, fully hand-maintained. Update `SUPPORTED_TAG`, `SUPPORTED_VERSIONS`, and the `isSameRelease(...)` guard. `INMS.bindExact` reflects on `art.arcane.iris.core.nms.<tag>.NMSBinding`, so an unedited selector rejects the new server before the new binding is ever loaded. Update `core/src/test/java/art/arcane/iris/core/nms/NmsBindingSelectorTest.java` in the same edit; it asserts the tag and the accepted/rejected versions.
|
||||
- Create the binding sources under `adapters/bukkit/nms/v<major>_<minor>_R<rev>/src/main/java/art/arcane/iris/core/nms/v<major>_<minor>_R<rev>/`, matching the existing set: `NMSBinding`, `IrisChunkGenerator`, `CustomBiomeSource`, `VanillaStructureBiomes`, `DatapackStructureStateFilter`, `ImportedFeatureStage`.
|
||||
|
||||
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 (currently `>=0.19.3`) 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` (currently `[65,)`) and the `forge` dependency versionRange (also `[65,)`) for the new Forge line. Both are hand-maintained.
|
||||
- `adapters/neoforge/src/main/resources/META-INF/neoforge.mods.toml` — `minecraft` versionRange is `[${minecraftVersion}]` (auto). `loaderVersion` (currently `[3,)`) is the javafml specification version, not the NeoForge version, and rarely moves. The `neoforge` dependency `versionRange` is **hardcoded** (currently `[26.2,)`) and is *not* templated from `minecraftVersion` — hand-edit it on every bump or the mod will load on the wrong NeoForge line.
|
||||
- `adapters/forge/src/main/resources/META-INF/mods.toml` — `minecraft` versionRange is `[${minecraftVersion}]` (auto). Update `loaderVersion` (currently `[65,66)`) and the `forge` dependency versionRange (also `[65,66)`). Both are hand-maintained and both are upper-bounded, so both must move on every Forge line bump.
|
||||
- `adapters/neoforge/src/main/resources/META-INF/neoforge.mods.toml` — `minecraft` versionRange is `[${minecraftVersion}]` (auto). `loaderVersion` (currently `[3,)`) is the javafml specification version, not the NeoForge version, and rarely moves. The `neoforge` dependency `versionRange` is **hardcoded** (currently `[26.2,26.3)`) and is *not* templated from `minecraftVersion` — hand-edit it on every bump or the mod will refuse to load on the new NeoForge line.
|
||||
|
||||
6. Re-verify the mapping-coupled files. Six files name Mojang-mapped classes, fields, and method descriptors directly. Nothing templates them, nothing fails fast at build time if a name moved, and a stale entry surfaces as a silent no-op or a load-time crash. Check every one against the new MC jar.
|
||||
|
||||
@@ -61,12 +65,12 @@ Stop when an upstream API, mapping, or loader artifact is unavailable; do not hi
|
||||
- `adapters/neoforge/src/main/resources/META-INF/accesstransformer.cfg`
|
||||
- both: `public net.minecraft.server.MinecraftServer levels` / `executor` / `storageSource`
|
||||
|
||||
Verify: the three ATs match the first three AW entries. Note the ATs have no `PackRepository` entry — Forge/NeoForge reach the pack sources through their own hooks, so do not add one without a reason. Wired via `minecraft { accessTransformer.from(...) }` (Forge) and `neoForge { accessTransformers.from(...) }` (NeoForge).
|
||||
Verify: the three ATs match the first three AW entries. Note the ATs have no `PackRepository` entry — Forge/NeoForge reach the pack sources through their own hooks, so do not add one without a reason. Wired via `minecraft { accessTransformer.from(...) }` in `adapters/forge/build.gradle` and `neoForge { accessTransformers.from(...) }` in `adapters/neoforge/build.gradle`; NeoForge additionally declares the file in an `[[accessTransformers]]` block in `neoforge.mods.toml`.
|
||||
|
||||
Mixin configs — three JSONs, eight mixin classes, all targeting Mojang-mapped members:
|
||||
Mixin configs — three JSONs, eight mixin classes, all targeting Mojang-mapped members. The JSONs only list class names; the mapped method names and descriptors below live in the `.java` mixin classes, so check those files, not the configs:
|
||||
|
||||
- `adapters/fabric/src/main/resources/irisworldgen.mixins.json`
|
||||
(package `art.arcane.iris.fabric.mixin`, `compatibilityLevel` `JAVA_25`, Fabric only)
|
||||
(package `art.arcane.iris.fabric.mixin`, `compatibilityLevel` `JAVA_21`, Fabric only)
|
||||
- `BlockItemMixin` -> `BlockItem.placeBlock`, `@At("RETURN")`
|
||||
- `BlockMixin` -> `Block.getDrops(...)` with a **full descriptor** (`BlockState, ServerLevel, BlockPos, BlockEntity, Entity, ItemInstance`) — the highest-churn entry in the repo; the parameter list changes across MC versions
|
||||
- `PackRepositoryMixin` -> `PackRepository.<init>`, `@At("RETURN")`
|
||||
@@ -76,7 +80,7 @@ Stop when an upstream API, mapping, or loader artifact is unavailable; do not hi
|
||||
- `LivingEntityLootMixin` -> `LivingEntity.dropFromLootTable(ServerLevel, DamageSource, boolean)` — full descriptor
|
||||
- `MobAwarenessMixin` -> `Mob.serverAiStep`, injecting at a **field target** (`Lnet/minecraft/world/entity/Mob;noActionTime:I`) — verify the field, not just the method
|
||||
- `adapters/modded-common/src/main/resources/irisworldgen.client.mixins.json`
|
||||
(package `art.arcane.iris.client.mixin`, client-only)
|
||||
(package `art.arcane.iris.client.mixin`, `compatibilityLevel` `JAVA_21`, classes listed under `client` rather than `mixins`)
|
||||
- `IrisWorldOpenFlowsMixin` -> `WorldOpenFlows.confirmWorldCreation` and `WorldOpenFlows.openWorldCheckWorldStemCompatibility`
|
||||
- `IrisWorldTypeEntryMixin` -> `WorldCreationUiState.WorldTypeEntry.describePreset`, plus a `@Shadow` member — shadows break silently if the field is renamed
|
||||
|
||||
@@ -85,11 +89,11 @@ Stop when an upstream API, mapping, or loader artifact is unavailable; do not hi
|
||||
Registration differs per loader and each place must list the same configs:
|
||||
- Fabric — `fabric.mod.json` `mixins` (all three; the client one gated on `"environment": "client"`).
|
||||
- NeoForge — `[[mixins]]` blocks in `neoforge.mods.toml` (entity + client).
|
||||
- Forge — no toml entry. The jar manifest attribute `MixinConfigs` in `adapters/forge/build.gradle` plus `--mixin.config` args on the `runClient`/`runServer` configurations (entity + client). Adding a mixin config on Forge means editing the manifest attribute *and* the run args.
|
||||
- Forge — no toml entry; FML 26.2 reads neither `[[mixins]]` nor `accessTransformers` from a Forge toml. The jar manifest attribute `MixinConfigs` in `adapters/forge/build.gradle` is the only shipping registration, and the `minecraft { runs { … } }` block passes `--mixin.config` separately (`client` gets entity + client, `server` gets entity only). Adding a mixin config on Forge means editing the manifest attribute *and* the relevant run args.
|
||||
|
||||
`injectors.defaultRequire` is `1` in all three configs, so a mixin that no longer applies fails the run instead of degrading quietly. Treat any "mixin apply failed" line as a bump blocker, and run both `runClient` and `runServer` per loader — client-only mixins are not exercised by a server run.
|
||||
|
||||
7. Reconcile the Fabric jar-in-jar list. `adapters/fabric/build.gradle` adds every Fabric API module to the `jij` configuration, which the `shadowJar` copies into `META-INF/jars` with the version stripped from the filename. The `jij` configuration is `transitive = false`, so the bundled set is exactly the declared set, and `fabric.mod.json` `jars` must list exactly those filenames. After changing the module list, confirm the jar agrees:
|
||||
7. Reconcile the Fabric jar-in-jar list across three places that must agree exactly. `adapters/fabric/build.gradle` adds every Fabric API module to the `jij` configuration, and `shadowJar` copies it into `META-INF/jars`, renaming each artifact through the `nestedFabricApiJars` map (an explicit module-to-filename table, not a version-stripping regex — a bundled jar with no map entry fails the build with `Undeclared Fabric API nested jar`). The `jij` configuration is `transitive = false`, so the bundled set is exactly the declared set. Adding or removing a module means editing the `jij` dependency list, `nestedFabricApiJars`, and the `jars` array in `fabric.mod.json` together. After changing the module list, confirm the jar agrees:
|
||||
|
||||
```
|
||||
unzip -l "dist/Iris v<version> [Fabric] <mc>+<loader>.jar" | grep META-INF/jars
|
||||
@@ -97,23 +101,26 @@ Stop when an upstream API, mapping, or loader artifact is unavailable; do not hi
|
||||
|
||||
An entry in `jars` with no matching nested jar makes the loader refuse the mod; a nested jar missing from `jars` is dead weight the loader never mounts.
|
||||
|
||||
8. Build and verify:
|
||||
- `./gradlew :core:check`
|
||||
- `./gradlew buildBukkit`
|
||||
8. Build and verify, in this order:
|
||||
- `./gradlew :core:check` — includes `bukkitPurityRatchet` and the NMS selector tests. Green before touching the platform builds.
|
||||
- `./gradlew buildBukkit` — runs `verifyBukkitArtifact` first, then drops the jar in `dist/`.
|
||||
- `./gradlew buildFabric`
|
||||
- `./gradlew buildForge`
|
||||
- `./gradlew buildNeoforge`
|
||||
|
||||
9. After a successful bump, re-run operator smoke and GoldenHash parity on all platforms (`31 - Operator Runbooks & Smoke Tests.md`, `32 - Determinism & Goldenhash.md`) and continue with `86 - Maintainer - Release Checklist.md` only after `87 - Maintainer - Release Readiness.md` allows GO or GO-WARN.
|
||||
Each `build*` task runs its artifact verifier as a dependency, so a missing resource, an unapplied mixin config, or a new Bukkit-coupled class fails the task rather than shipping. `./build-all.sh` runs all four serialized with local VolmLib substitution off; use it for the final pass. Good looks like: four jars in `dist/` carrying the new version strings, and a `Verified …` line for every platform.
|
||||
|
||||
9. After a successful bump, re-run the operator runbooks and GoldenHash parity on all platforms (`31 - Operator Runbooks.md`, `32 - Determinism & Goldenhash.md`) and continue with `86 - Maintainer - Release Checklist.md` only after `87 - Maintainer - Release Readiness.md` allows GO or GO-WARN.
|
||||
|
||||
## Derived automatically (do not hand-edit on a version bump)
|
||||
|
||||
- Bukkit plugin `api-version` — `adapters/bukkit/plugin/build.gradle` reads `apiVersion`.
|
||||
- `BuildConstants.MINECRAFT_VERSION` — stamped by the `generateTemplates` task in `core/build.gradle` from `minecraftVersion`; consumed by `Tasks.supportedVersions`.
|
||||
- Bukkit plugin `api-version` — `adapters/bukkit/plugin/build.gradle` expands `apiVersion` into both `plugin.yml` and `paper-plugin.yml` at `processResources`.
|
||||
- `BuildConstants.MINECRAFT_VERSION` — stamped by the `generateTemplates` task in `core/build.gradle` from `minecraftVersion` (template at `core/src/main/templates/BuildConstants.java`); 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.
|
||||
- The three loader jar names and the `com.mojang:minecraft` coordinate — composed from `minecraftVersion` in the build scripts. The CraftBukkit jar name is the exception: it carries `bukkitMinecraftRange`, not `minecraftVersion` (step 1).
|
||||
|
||||
## 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.
|
||||
- `build.gradle`, the adapter `build.gradle` files, and `settings.gradle` carry defensive `.getOrElse(...)` 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. `bukkitMinecraftRange` is the one exception — it has no `gradle.properties` entry, so its `'26.1.2-26.2'` default is the live value.
|
||||
- The Java literals `"26.2"` and `"26.1.2"` intentionally remain in `DataVersion.java` (structural enum constants), `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.
|
||||
- `NmsBindingSelector.java` and `NmsBindingSelectorTest.java` also hardcode MC version literals, but those are *not* intentional leftovers — they are required edits (step 4).
|
||||
|
||||
Reference in New Issue
Block a user