From 3cd007871c3c21ad9beba6c3adad80e6bbc12360 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=97=E3=82=8D=E3=81=97=E3=82=85=E3=82=93?= <39247022+Siroshun09@users.noreply.github.com> Date: Sat, 3 Oct 2026 13:14:37 +0900 Subject: [PATCH 1/8] docs: add Minecraft version update guide --- docs/how-to-update-minecraft-version.md | 239 ++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 docs/how-to-update-minecraft-version.md diff --git a/docs/how-to-update-minecraft-version.md b/docs/how-to-update-minecraft-version.md new file mode 100644 index 0000000000..285e6e7a88 --- /dev/null +++ b/docs/how-to-update-minecraft-version.md @@ -0,0 +1,239 @@ +# How to update the Minecraft version + +This document describes the repeatable workflow for updating Box to a new Minecraft/Paper version. + +The procedure is based on previous Minecraft update work, especially: + +- [#490 - Minecraft 1.21.7](https://github.com/okocraft/Box/pull/490) +- [#525 - Minecraft 1.21.9 / 1.21.10](https://github.com/okocraft/Box/pull/525) +- [#564 - Minecraft 26.1](https://github.com/okocraft/Box/pull/564) +- [Minecraft 26.2 update commit](https://github.com/okocraft/Box/commit/b6b433951d78557caa558439bbffa3291b578a8a) + +Older PRs contain version-specific module changes that are no longer required after the versioning refactor in June 2026. Follow the current repository structure described below. + +## Inputs + +Before starting, determine: + +- the previous Minecraft version currently supported by Box; +- the target Minecraft version; +- a Paper API build compatible with the target version; +- the target Minecraft data version if item rename mappings are required. + +Prefer processing released Minecraft versions sequentially when several versions were skipped. This makes item additions and renames easier to review and preserves migration mappings at the correct data-version boundary. + +## 1. Update the Paper dependency + +Check `gradle/libs.versions.toml`. + +Renovate normally updates `io.papermc.paper:paper-api`, so this may already be done. If not, update `paper` to a build for the target Minecraft version. + +Do not change unrelated dependencies as part of the Minecraft update. Update `paper-javadoc` only when a matching version is available and the project needs it; it does not have to move in the same commit as `paper`. + +Then run: + +```shell +./gradlew build +``` + +Fix compilation errors caused by Paper/Bukkit API changes before continuing. Previous updates required source changes outside the version/data files, so compiler errors must be treated as part of the update rather than bypassed. + +## 2. Configure the data generator + +Edit `data-generator/build.gradle.kts`: + +```kotlin +val previousMinecraftVersion = "" +val minecraftVersion = "" +``` + +`previousMinecraftVersion` must correspond to a file already present in: + +```text +data-generator/src/main/resources/generated/items/.txt +``` + +The data generator starts a Paper server for `minecraftVersion` and writes generated files under: + +```text +data-generator/build/resources/generated-data/ +``` + +Run it with: + +```shell +./gradlew :box-data-generator:runServer +``` + +The relevant outputs are: + +```text +.txt +-new-items.txt +-uncategorized-items.txt +``` + +- `.txt` is the complete generated default-item list. +- `-new-items.txt` is the difference from the previous version after known renames are applied. +- `-uncategorized-items.txt` contains default items that are not covered by the bundled category definitions. + +## 3. Commit the generated item list + +Copy: + +```text +data-generator/build/resources/generated-data/.txt +``` + +to: + +```text +data-generator/src/main/resources/generated/items/.txt +``` + +The `-new-items.txt` and `-uncategorized-items.txt` files are review aids and are not normally committed. + +## 4. Categorize new items + +Review both diagnostic files. + +For each new item, add it to the appropriate category in: + +```text +features/category/src/main/resources/default_categories.yml +``` + +Items introduced in the target version must be guarded by their Minecraft data version: + +```yaml + - : +``` + +If an item replaces an older name, the category entry can use the rename syntax already used in this file, for example: + +```yaml + - OLD_NAME;:NEW_NAME +``` + +If the new Minecraft release introduces a group that deserves its own default category, also add that category to: + +```text +features/category/src/main/java/net/okocraft/box/feature/category/internal/category/defaults/DefaultCategories.java +``` + +The Minecraft 26.2 update is an example: it added the `sulfur-caves` category in both the Java category list and `default_categories.yml`. + +Items that should never be offered as normal Box items, such as internal/test-only items, should be placed in the existing `unavailable` category rather than left uncategorized. + +After editing the categories, rerun: + +```shell +./gradlew :box-data-generator:runServer +``` + +The goal is for `-uncategorized-items.txt` to be empty. + +## 5. Handle renamed items + +Only do this when Minecraft renamed an item identifier. + +Add a resource file named after the Minecraft data version: + +```text +item-provider/src/main/resources/.txt +``` + +Each mapping is: + +```text +OLD_NAME:NEW_NAME +``` + +For example, Minecraft 1.21.9 used: + +```text +CHAIN:IRON_CHAIN +``` + +Then: + +1. add a corresponding `MCDataVersion` constant in + `api/src/main/java/net/okocraft/box/api/util/MCDataVersion.java`; +2. add that constant to `RenamedItems.VERSIONS` in + `item-provider/src/main/java/net/okocraft/box/item/RenamedItems.java`; +3. rerun the data generator so `-new-items.txt` does not incorrectly report renamed items as newly added items; +4. update category entries to preserve the old name before the rename and the new name from the rename data version onward. + +Do not add an `MCDataVersion` constant merely because Minecraft released a new version. Since the June 2026 refactor, constants are only needed when code needs to refer to that exact data-version boundary, such as an item rename migration. + +## 6. Review API-specific breakage + +Minecraft updates can require source changes unrelated to generated items. Typical signals are compilation failures or behavior changes in Paper/Bukkit APIs. + +Examples from previous updates include: + +- changed Adventure/Paper component APIs; +- changed sound/category APIs; +- changed item metadata APIs; +- behavior changes around projectiles or item types. + +Keep these fixes in the same Minecraft update only when they are required for the target version. + +## 7. Verify + +Run the following checks after the generated data and categories are complete: + +```shell +./gradlew :box-data-generator:runServer +./gradlew build +``` + +Verify that: + +- `-uncategorized-items.txt` is empty; +- `-new-items.txt` contains only genuinely new items; +- `data-generator/src/main/resources/generated/items/.txt` matches the newly generated full item list; +- every rename has a migration resource and is registered in `RenamedItems.VERSIONS`; +- the project compiles and tests pass; +- any Paper/Bukkit API breakage has been handled intentionally. + +## Files normally changed + +For a straightforward update after the current versioning refactor, expect changes to a subset of: + +```text +gradle/libs.versions.toml +data-generator/build.gradle.kts +data-generator/src/main/resources/generated/items/.txt +features/category/src/main/resources/default_categories.yml +features/category/src/main/java/net/okocraft/box/feature/category/internal/category/defaults/DefaultCategories.java +``` + +When item identifiers are renamed, also expect: + +```text +api/src/main/java/net/okocraft/box/api/util/MCDataVersion.java +item-provider/src/main/java/net/okocraft/box/item/RenamedItems.java +item-provider/src/main/resources/.txt +``` + +Other source files should only change when the new Paper/Bukkit API requires compatibility fixes. + +## Automation boundary + +The following parts are suitable for automation: + +1. update `previousMinecraftVersion` and `minecraftVersion`; +2. run the data generator; +3. copy `.txt` into the committed generated-item directory; +4. report the contents of `-new-items.txt` and `-uncategorized-items.txt`; +5. run the build and report compilation/test failures. + +The following parts require review rather than blind automation: + +- deciding the correct category for each new item; +- deciding whether a new default category should be introduced; +- identifying semantic item renames and migration mappings; +- adapting Box code to Paper/Bukkit API changes. + +An automated agent should stop and request review when any of those decisions are required instead of inventing mappings or categories. From ec55107c722775ee4fd125ce8ae58a880ed129d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=97=E3=82=8D=E3=81=97=E3=82=85=E3=82=93?= <39247022+Siroshun09@users.noreply.github.com> Date: Sat, 3 Oct 2026 15:21:26 +0900 Subject: [PATCH 2/8] docs: incorporate Minecraft 26.3 update learnings --- docs/how-to-update-minecraft-version.md | 172 +++++++++++++++++++++--- 1 file changed, 156 insertions(+), 16 deletions(-) diff --git a/docs/how-to-update-minecraft-version.md b/docs/how-to-update-minecraft-version.md index 285e6e7a88..dd90a5d95f 100644 --- a/docs/how-to-update-minecraft-version.md +++ b/docs/how-to-update-minecraft-version.md @@ -8,6 +8,7 @@ The procedure is based on previous Minecraft update work, especially: - [#525 - Minecraft 1.21.9 / 1.21.10](https://github.com/okocraft/Box/pull/525) - [#564 - Minecraft 26.1](https://github.com/okocraft/Box/pull/564) - [Minecraft 26.2 update commit](https://github.com/okocraft/Box/commit/b6b433951d78557caa558439bbffa3291b578a8a) +- [#614 - Minecraft 26.3](https://github.com/okocraft/Box/pull/614) Older PRs contain version-specific module changes that are no longer required after the versioning refactor in June 2026. Follow the current repository structure described below. @@ -18,9 +19,11 @@ Before starting, determine: - the previous Minecraft version currently supported by Box; - the target Minecraft version; - a Paper API build compatible with the target version; -- the target Minecraft data version if item rename mappings are required. +- the target Minecraft data version. -Prefer processing released Minecraft versions sequentially when several versions were skipped. This makes item additions and renames easier to review and preserves migration mappings at the correct data-version boundary. +The data version is used to guard newly introduced items in the bundled category definitions and, when necessary, to define item rename migration boundaries. + +Prefer processing released Minecraft versions sequentially when several versions were skipped. This makes item additions, removals, and renames easier to review and preserves migration mappings at the correct data-version boundary. ## 1. Update the Paper dependency @@ -38,7 +41,7 @@ Then run: Fix compilation errors caused by Paper/Bukkit API changes before continuing. Previous updates required source changes outside the version/data files, so compiler errors must be treated as part of the update rather than bypassed. -## 2. Configure the data generator +## 2. Configure and run the data generator Edit `data-generator/build.gradle.kts`: @@ -59,12 +62,53 @@ The data generator starts a Paper server for `minecraftVersion` and writes gener data-generator/build/resources/generated-data/ ``` -Run it with: +### Ensure `runServer` stops automatically + +A normal Paper server keeps running after the plugin has generated its data. The data generator therefore supports the system property: + +```text +net.okocraft.box.datagenerator.auto-stop +``` + +When this property is enabled, `data-generator/src/main/java/net/okocraft/box/datagenerator/Main.java` must schedule shutdown after generation: + +```java +private static final boolean AUTO_STOP = + Boolean.getBoolean("net.okocraft.box.datagenerator.auto-stop"); + +@Override +public void onEnable() { + this.generateData(); + if (AUTO_STOP) { + Bukkit.getGlobalRegionScheduler().run(this, task -> Bukkit.shutdown()); + } +} +``` + +Use `Bukkit.getGlobalRegionScheduler()` so shutdown is scheduled for the next scheduler tick instead of stopping the server directly inside plugin enable processing. + +The `runServer` task in `data-generator/build.gradle.kts` must enable the property: + +```kotlin +runServer { + minecraftVersion(minecraftVersion) + systemProperty("com.mojang.eula.agree", "true") + systemProperty("paper.disablePluginRemapping", "true") + systemProperty("net.okocraft.box.datagenerator.auto-stop", "true") + // ... +} +``` + +This infrastructure was introduced during the Minecraft 26.3 update. Once it exists, future version updates normally only need to keep it enabled rather than changing the implementation. + +Run the generator with: ```shell ./gradlew :box-data-generator:runServer ``` +The command should return by itself after data generation. A server that remains running indicates that auto-stop is not working and should be treated as a failed generation run. + The relevant outputs are: ```text @@ -77,6 +121,65 @@ The relevant outputs are: - `-new-items.txt` is the difference from the previous version after known renames are applied. - `-uncategorized-items.txt` contains default items that are not covered by the bundled category definitions. +### Alternative: generate with a temporary GitHub Actions workflow + +If the generator cannot be run locally, add a temporary workflow under `.github/workflows/` on the update branch and upload the generated directory as an artifact. + +Use the repository's current Java and action versions. The following is a template; replace the placeholders for each update: + +```yaml +name: Minecraft data generation + +on: + push: + branches: [] + +jobs: + generate: + runs-on: ubuntu-latest + timeout-minutes: 15 + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: '25' + + - uses: gradle/actions/setup-gradle@v4 + + - run: chmod +x ./gradlew + + - name: Generate data + run: ./gradlew :box-data-generator:runServer + + - name: Check generated files + run: | + test -s data-generator/build/resources/generated-data/.txt + test -f data-generator/build/resources/generated-data/-new-items.txt + test -f data-generator/build/resources/generated-data/-uncategorized-items.txt + + - uses: actions/upload-artifact@v4 + if: always() + with: + name: minecraft--data + path: data-generator/build/resources/generated-data/ + if-no-files-found: error +``` + +Do not make a shell timeout count as a successful generation. The workflow-level timeout is only a safety limit; `runServer` must terminate normally through auto-stop. + +After the workflow succeeds: + +1. download the `minecraft--data` artifact; +2. inspect the generated full list, new-item list, and uncategorized list; +3. make the required repository changes; +4. rerun the workflow to validate the final category coverage if necessary; +5. remove the temporary workflow from the branch before the update PR is considered complete. + +The Minecraft 26.3 update used this approach because the generator could not be run locally. The temporary workflow was removed after the generated data and category coverage had been verified. + ## 3. Commit the generated item list Copy: @@ -91,11 +194,15 @@ to: data-generator/src/main/resources/generated/items/.txt ``` +When using the GitHub Actions fallback, copy the same file from the downloaded artifact. + The `-new-items.txt` and `-uncategorized-items.txt` files are review aids and are not normally committed. +Compare the generated complete list against the previous version as an additional sanity check. Unexpected removals may indicate an identifier rename or another compatibility issue that needs investigation. + ## 4. Categorize new items -Review both diagnostic files. +Review both diagnostic files, especially `-new-items.txt` and `-uncategorized-items.txt`. For each new item, add it to the appropriate category in: @@ -125,13 +232,27 @@ The Minecraft 26.2 update is an example: it added the `sulfur-caves` category in Items that should never be offered as normal Box items, such as internal/test-only items, should be placed in the existing `unavailable` category rather than left uncategorized. +### How to decide categories + +When the task includes categorizing new items, do not stop merely because classification requires judgment. Proceed with classification when there is sufficient evidence from: + +- existing Box categories and how similar items are already grouped; +- item families and naming patterns in the generated data; +- official Minecraft release notes, changelogs, or other official descriptions of the new content. + +After classifying, rerun the generator and use the uncategorized output to verify coverage. + +Ask for clarification only when the existing category structure and official change information still do not provide a defensible classification. Do not invent a new semantic grouping when the available evidence is genuinely ambiguous. + +For example, Minecraft 26.3 added 121 generated item identifiers and removed none compared with 26.2. The update used data version 5023 and classified the new items into existing categories, including Poplar items under `woods-2`, concrete variants under `concretes`, wool/cushion/bed items under `wools`, and explorer-map items under `tools`. These numbers and data version are historical facts for the 26.3 update only; always derive the corresponding values again for future versions. + After editing the categories, rerun: ```shell ./gradlew :box-data-generator:runServer ``` -The goal is for `-uncategorized-items.txt` to be empty. +The goal is for `-uncategorized-items.txt` to exist and be empty. ## 5. Handle renamed items @@ -166,6 +287,8 @@ Then: Do not add an `MCDataVersion` constant merely because Minecraft released a new version. Since the June 2026 refactor, constants are only needed when code needs to refer to that exact data-version boundary, such as an item rename migration. +Minecraft 26.3 had no removed generated identifiers compared with 26.2, so no rename migration was needed in that update. Do not assume this will be true for later versions. + ## 6. Review API-specific breakage Minecraft updates can require source changes unrelated to generated items. Typical signals are compilation failures or behavior changes in Paper/Bukkit APIs. @@ -188,14 +311,21 @@ Run the following checks after the generated data and categories are complete: ./gradlew build ``` +If local generation is unavailable, perform the equivalent generator checks in the temporary GitHub Actions workflow and download its artifact. + Verify that: -- `-uncategorized-items.txt` is empty; -- `-new-items.txt` contains only genuinely new items; -- `data-generator/src/main/resources/generated/items/.txt` matches the newly generated full item list; +- `-uncategorized-items.txt` exists and is empty; +- `-new-items.txt` contains only genuinely new items after known renames are applied; +- the generated complete `.txt` and the committed `data-generator/src/main/resources/generated/items/.txt` are identical; +- the previous and target complete lists have been compared for unexpected removals; +- `runServer` exits after generation and the Paper server does not remain running; - every rename has a migration resource and is registered in `RenamedItems.VERSIONS`; - the project compiles and tests pass; -- any Paper/Bukkit API breakage has been handled intentionally. +- any Paper/Bukkit API breakage has been handled intentionally; +- any temporary GitHub Actions workflow used for generation has been removed from the final branch. + +For a strong equality check between the generated and committed full lists, compare the files byte-for-byte or compare their Git blob hashes. Minecraft 26.3 was verified by matching the generated artifact's complete list with the committed `26.3.txt`. ## Files normally changed @@ -217,6 +347,14 @@ item-provider/src/main/java/net/okocraft/box/item/RenamedItems.java item-provider/src/main/resources/.txt ``` +The auto-stop support added during the Minecraft 26.3 update also changed: + +```text +data-generator/src/main/java/net/okocraft/box/datagenerator/Main.java +``` + +That is a one-time data-generator infrastructure change, not a file that should normally change for every Minecraft version. + Other source files should only change when the new Paper/Bukkit API requires compatibility fixes. ## Automation boundary @@ -224,16 +362,18 @@ Other source files should only change when the new Paper/Bukkit API requires com The following parts are suitable for automation: 1. update `previousMinecraftVersion` and `minecraftVersion`; -2. run the data generator; +2. run the data generator locally or through a temporary GitHub Actions workflow; 3. copy `.txt` into the committed generated-item directory; -4. report the contents of `-new-items.txt` and `-uncategorized-items.txt`; -5. run the build and report compilation/test failures. +4. compare the previous and target complete item lists; +5. report the contents of `-new-items.txt` and `-uncategorized-items.txt`; +6. run the build and report compilation/test failures; +7. verify that the generator terminates and that the committed complete list matches the generated output. -The following parts require review rather than blind automation: +The following parts require evidence-based review rather than blind automation: -- deciding the correct category for each new item; +- assigning new items to categories; - deciding whether a new default category should be introduced; - identifying semantic item renames and migration mappings; - adapting Box code to Paper/Bukkit API changes. -An automated agent should stop and request review when any of those decisions are required instead of inventing mappings or categories. +If the requested task includes classification, an automated agent should use the existing category structure and official Minecraft change information to classify and validate the new items instead of stopping at the first judgment call. It should request clarification only when those sources do not provide enough evidence for a defensible decision. From b5d71d6f87600f978d6361e80a6055c7d129c523 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=97=E3=82=8D=E3=81=97=E3=82=85=E3=82=93?= <39247022+Siroshun09@users.noreply.github.com> Date: Sat, 3 Oct 2026 20:08:21 +0900 Subject: [PATCH 3/8] docs: document category item ordering --- docs/how-to-update-minecraft-version.md | 31 +++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/how-to-update-minecraft-version.md b/docs/how-to-update-minecraft-version.md index dd90a5d95f..deec47be1a 100644 --- a/docs/how-to-update-minecraft-version.md +++ b/docs/how-to-update-minecraft-version.md @@ -244,7 +244,33 @@ After classifying, rerun the generator and use the uncategorized output to verif Ask for clarification only when the existing category structure and official change information still do not provide a defensible classification. Do not invent a new semantic grouping when the available evidence is genuinely ambiguous. -For example, Minecraft 26.3 added 121 generated item identifiers and removed none compared with 26.2. The update used data version 5023 and classified the new items into existing categories, including Poplar items under `woods-2`, concrete variants under `concretes`, wool/cushion/bed items under `wools`, and explorer-map items under `tools`. These numbers and data version are historical facts for the 26.3 update only; always derive the corresponding values again for future versions. +### Place new items consistently within each category + +Do not append all new items to the end of a category as one block. Preserve the category's existing organization and place each new item near the most closely related existing items. + +Use the local ordering pattern already present in the category as the primary guide. For example: + +- when a category is grouped by material or family, insert the new family alongside the corresponding existing families; +- when a category is grouped by shape or variant, keep new slabs, stairs, carpets, beds, and similar variants in the corresponding shape block; +- when an item extends a specific base item or concept, place it immediately after or near that base item; +- for plants and other natural items, place them near the most closely related existing plants instead of at the category boundary. + +Minecraft 26.3 is an example of this placement rule: + +- Poplar items were inserted into the existing wood-type ordering in `woods-2`; +- Concrete and Wool slabs and stairs were grouped with the existing shape-based sections instead of being appended after all older entries; +- Explorer Map items were placed immediately after `MAP` in `tools`; +- `SHELF_MUSHROOM` and `RED_SHRUB` were placed near related plant entries in `farms` and `flowers`. + +Placement changes must not alter the classification itself. After reorganizing the entries, compare the state before and after reordering and verify that: + +- the number of newly added items is unchanged; +- every new item remains in the same category; +- every new item retains the same Minecraft data-version guard. + +A useful invariant is the set of `(category, data-version, item)` tuples for the target version: reordering may change line positions, but it must not change that set. + +For example, Minecraft 26.3 added 121 generated item identifiers and removed none compared with 26.2. The update used data version 5023 and classified the new items into existing categories, including Poplar items under `woods-2`, concrete variants under `concretes`, wool/cushion/bed items under `wools`, and explorer-map items under `tools`. The placement was then adjusted according to the rules above without changing the 121-item count, category assignments, or data version. These numbers and data version are historical facts for the 26.3 update only; always derive the corresponding values again for future versions. After editing the categories, rerun: @@ -317,6 +343,7 @@ Verify that: - `-uncategorized-items.txt` exists and is empty; - `-new-items.txt` contains only genuinely new items after known renames are applied; +- after any category-ordering cleanup, the count and set of `(category, data-version, item)` tuples for newly added items are unchanged; - the generated complete `.txt` and the committed `data-generator/src/main/resources/generated/items/.txt` are identical; - the previous and target complete lists have been compared for unexpected removals; - `runServer` exits after generation and the Paper server does not remain running; @@ -371,7 +398,7 @@ The following parts are suitable for automation: The following parts require evidence-based review rather than blind automation: -- assigning new items to categories; +- assigning new items to categories and placing them consistently with the category's existing ordering; - deciding whether a new default category should be introduced; - identifying semantic item renames and migration mappings; - adapting Box code to Paper/Bukkit API changes. From 4751d8d26f49dc809a427948af7b4388d18280b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=97=E3=82=8D=E3=81=97=E3=82=85=E3=82=93?= <39247022+Siroshun09@users.noreply.github.com> Date: Sat, 3 Oct 2026 20:15:15 +0900 Subject: [PATCH 4/8] docs: streamline Minecraft update guide --- docs/how-to-update-minecraft-version.md | 346 ++++++------------------ 1 file changed, 86 insertions(+), 260 deletions(-) diff --git a/docs/how-to-update-minecraft-version.md b/docs/how-to-update-minecraft-version.md index deec47be1a..9e05afbcdd 100644 --- a/docs/how-to-update-minecraft-version.md +++ b/docs/how-to-update-minecraft-version.md @@ -1,45 +1,24 @@ # How to update the Minecraft version -This document describes the repeatable workflow for updating Box to a new Minecraft/Paper version. +This document describes the workflow for updating Box to a new Minecraft/Paper version using the current repository structure. -The procedure is based on previous Minecraft update work, especially: +## 1. Prepare the target version -- [#490 - Minecraft 1.21.7](https://github.com/okocraft/Box/pull/490) -- [#525 - Minecraft 1.21.9 / 1.21.10](https://github.com/okocraft/Box/pull/525) -- [#564 - Minecraft 26.1](https://github.com/okocraft/Box/pull/564) -- [Minecraft 26.2 update commit](https://github.com/okocraft/Box/commit/b6b433951d78557caa558439bbffa3291b578a8a) -- [#614 - Minecraft 26.3](https://github.com/okocraft/Box/pull/614) +Determine: -Older PRs contain version-specific module changes that are no longer required after the versioning refactor in June 2026. Follow the current repository structure described below. - -## Inputs - -Before starting, determine: - -- the previous Minecraft version currently supported by Box; +- the currently committed Minecraft version; - the target Minecraft version; -- a Paper API build compatible with the target version; -- the target Minecraft data version. - -The data version is used to guard newly introduced items in the bundled category definitions and, when necessary, to define item rename migration boundaries. - -Prefer processing released Minecraft versions sequentially when several versions were skipped. This makes item additions, removals, and renames easier to review and preserves migration mappings at the correct data-version boundary. - -## 1. Update the Paper dependency +- a Paper API build compatible with the target version. -Check `gradle/libs.versions.toml`. +Check `gradle/libs.versions.toml`. Renovate may already have updated `paper`; otherwise update it to a compatible build. -Renovate normally updates `io.papermc.paper:paper-api`, so this may already be done. If not, update `paper` to a build for the target Minecraft version. - -Do not change unrelated dependencies as part of the Minecraft update. Update `paper-javadoc` only when a matching version is available and the project needs it; it does not have to move in the same commit as `paper`. - -Then run: +Run: ```shell ./gradlew build ``` -Fix compilation errors caused by Paper/Bukkit API changes before continuing. Previous updates required source changes outside the version/data files, so compiler errors must be treated as part of the update rather than bypassed. +Resolve compilation errors caused by Paper/Bukkit API changes as part of the version update. ## 2. Configure and run the data generator @@ -50,65 +29,26 @@ val previousMinecraftVersion = "" val minecraftVersion = "" ``` -`previousMinecraftVersion` must correspond to a file already present in: +`previousMinecraftVersion` must match an existing file: ```text data-generator/src/main/resources/generated/items/.txt ``` -The data generator starts a Paper server for `minecraftVersion` and writes generated files under: +Run: -```text -data-generator/build/resources/generated-data/ +```shell +./gradlew :box-data-generator:runServer ``` -### Ensure `runServer` stops automatically +The existing `runServer` configuration enables `net.okocraft.box.datagenerator.auto-stop`, so the server must stop automatically after generation. If the process remains running, treat the generation as failed and fix the auto-stop behavior before continuing. -A normal Paper server keeps running after the plugin has generated its data. The data generator therefore supports the system property: +Generated files are written to: ```text -net.okocraft.box.datagenerator.auto-stop -``` - -When this property is enabled, `data-generator/src/main/java/net/okocraft/box/datagenerator/Main.java` must schedule shutdown after generation: - -```java -private static final boolean AUTO_STOP = - Boolean.getBoolean("net.okocraft.box.datagenerator.auto-stop"); - -@Override -public void onEnable() { - this.generateData(); - if (AUTO_STOP) { - Bukkit.getGlobalRegionScheduler().run(this, task -> Bukkit.shutdown()); - } -} -``` - -Use `Bukkit.getGlobalRegionScheduler()` so shutdown is scheduled for the next scheduler tick instead of stopping the server directly inside plugin enable processing. - -The `runServer` task in `data-generator/build.gradle.kts` must enable the property: - -```kotlin -runServer { - minecraftVersion(minecraftVersion) - systemProperty("com.mojang.eula.agree", "true") - systemProperty("paper.disablePluginRemapping", "true") - systemProperty("net.okocraft.box.datagenerator.auto-stop", "true") - // ... -} -``` - -This infrastructure was introduced during the Minecraft 26.3 update. Once it exists, future version updates normally only need to keep it enabled rather than changing the implementation. - -Run the generator with: - -```shell -./gradlew :box-data-generator:runServer +data-generator/build/resources/generated-data/ ``` -The command should return by itself after data generation. A server that remains running indicates that auto-stop is not working and should be treated as a failed generation run. - The relevant outputs are: ```text @@ -117,70 +57,27 @@ The relevant outputs are: -uncategorized-items.txt ``` -- `.txt` is the complete generated default-item list. -- `-new-items.txt` is the difference from the previous version after known renames are applied. -- `-uncategorized-items.txt` contains default items that are not covered by the bundled category definitions. - -### Alternative: generate with a temporary GitHub Actions workflow - -If the generator cannot be run locally, add a temporary workflow under `.github/workflows/` on the update branch and upload the generated directory as an artifact. - -Use the repository's current Java and action versions. The following is a template; replace the placeholders for each update: - -```yaml -name: Minecraft data generation - -on: - push: - branches: [] - -jobs: - generate: - runs-on: ubuntu-latest - timeout-minutes: 15 - - steps: - - uses: actions/checkout@v4 - - - uses: actions/setup-java@v4 - with: - distribution: temurin - java-version: '25' - - - uses: gradle/actions/setup-gradle@v4 - - - run: chmod +x ./gradlew - - - name: Generate data - run: ./gradlew :box-data-generator:runServer +- `.txt`: complete default-item list for the target version. +- `-new-items.txt`: items not present in the previous version after known rename mappings are applied. +- `-uncategorized-items.txt`: items missing from the default categories. Each line includes the current Minecraft data version; use that generated value when adding version guards. - - name: Check generated files - run: | - test -s data-generator/build/resources/generated-data/.txt - test -f data-generator/build/resources/generated-data/-new-items.txt - test -f data-generator/build/resources/generated-data/-uncategorized-items.txt +Do not reuse a data-version value from an older Minecraft update. - - uses: actions/upload-artifact@v4 - if: always() - with: - name: minecraft--data - path: data-generator/build/resources/generated-data/ - if-no-files-found: error -``` +### If the generator cannot run locally -Do not make a shell timeout count as a successful generation. The workflow-level timeout is only a safety limit; `runServer` must terminate normally through auto-stop. +Create a temporary workflow under `.github/workflows/` on the update branch. It should: -After the workflow succeeds: +1. check out the branch; +2. use the repository's current Java/Gradle setup; +3. run `./gradlew :box-data-generator:runServer`; +4. verify that the three generated files exist; +5. upload `data-generator/build/resources/generated-data/` as an artifact. -1. download the `minecraft--data` artifact; -2. inspect the generated full list, new-item list, and uncategorized list; -3. make the required repository changes; -4. rerun the workflow to validate the final category coverage if necessary; -5. remove the temporary workflow from the branch before the update PR is considered complete. +Use a workflow-level timeout only as a failure safeguard. Do not make a timed-out `runServer` invocation count as success; the command must terminate normally through auto-stop. -The Minecraft 26.3 update used this approach because the generator could not be run locally. The temporary workflow was removed after the generated data and category coverage had been verified. +Download the artifact, use it for the update and verification, then delete the temporary workflow before the PR is complete. -## 3. Commit the generated item list +## 3. Commit the generated complete list Copy: @@ -194,213 +91,142 @@ to: data-generator/src/main/resources/generated/items/.txt ``` -When using the GitHub Actions fallback, copy the same file from the downloaded artifact. +If generation ran in GitHub Actions, copy the file from the downloaded artifact instead. -The `-new-items.txt` and `-uncategorized-items.txt` files are review aids and are not normally committed. +Compare the previous and target complete lists. Investigate any removed identifiers because they may indicate item renames or other compatibility changes. -Compare the generated complete list against the previous version as an additional sanity check. Unexpected removals may indicate an identifier rename or another compatibility issue that needs investigation. +The `-new-items.txt` and `-uncategorized-items.txt` files are review artifacts and are not committed. ## 4. Categorize new items -Review both diagnostic files, especially `-new-items.txt` and `-uncategorized-items.txt`. - -For each new item, add it to the appropriate category in: +Use `-new-items.txt` and `-uncategorized-items.txt` to update: ```text features/category/src/main/resources/default_categories.yml ``` -Items introduced in the target version must be guarded by their Minecraft data version: +Add newly introduced items with the data version emitted by the generator: ```yaml - : ``` -If an item replaces an older name, the category entry can use the rename syntax already used in this file, for example: +Classify items using, in order: -```yaml - - OLD_NAME;:NEW_NAME -``` +1. existing Box categories and the placement of similar items; +2. item-family and naming patterns; +3. official Minecraft release notes or changelogs. + +If the task includes classification, continue through classification and validation when these sources provide a defensible answer. Ask for clarification only when they do not. + +Items that should not be available as normal Box items belong in the existing `unavailable` category rather than being left uncategorized. -If the new Minecraft release introduces a group that deserves its own default category, also add that category to: +If the release introduces a group that genuinely requires a new default category, update both: ```text +features/category/src/main/resources/default_categories.yml features/category/src/main/java/net/okocraft/box/feature/category/internal/category/defaults/DefaultCategories.java ``` -The Minecraft 26.2 update is an example: it added the `sulfur-caves` category in both the Java category list and `default_categories.yml`. - -Items that should never be offered as normal Box items, such as internal/test-only items, should be placed in the existing `unavailable` category rather than left uncategorized. - -### How to decide categories - -When the task includes categorizing new items, do not stop merely because classification requires judgment. Proceed with classification when there is sufficient evidence from: - -- existing Box categories and how similar items are already grouped; -- item families and naming patterns in the generated data; -- official Minecraft release notes, changelogs, or other official descriptions of the new content. +### Preserve category ordering -After classifying, rerun the generator and use the uncategorized output to verify coverage. +Do not append all new items to the end of a category. Follow the local ordering already used in that category and place each item near related existing entries. -Ask for clarification only when the existing category structure and official change information still do not provide a defensible classification. Do not invent a new semantic grouping when the available evidence is genuinely ambiguous. +Current ordering patterns include: -### Place new items consistently within each category +- wood families in `woods-2`: keep each new wood type aligned with the corresponding planks, slabs, stairs, logs, wood, leaves, saplings, signs, boats, and other wood variants; +- `concretes` and `wools`: group variants by shape/type, such as slabs together and stairs together; +- `tools`: place specialized map items immediately after `MAP`; +- plant-related categories such as `farms` and `flowers`: place new plants near the most closely related existing plants. -Do not append all new items to the end of a category as one block. Preserve the category's existing organization and place each new item near the most closely related existing items. +Reordering must not change classification. After placement cleanup, verify that the newly added items have exactly the same: -Use the local ordering pattern already present in the category as the primary guide. For example: +- item count; +- category assignments; +- data-version guards. -- when a category is grouped by material or family, insert the new family alongside the corresponding existing families; -- when a category is grouped by shape or variant, keep new slabs, stairs, carpets, beds, and similar variants in the corresponding shape block; -- when an item extends a specific base item or concept, place it immediately after or near that base item; -- for plants and other natural items, place them near the most closely related existing plants instead of at the category boundary. +Equivalently, the set of `(category, data-version, item)` tuples for the target version must be unchanged by reordering. -Minecraft 26.3 is an example of this placement rule: - -- Poplar items were inserted into the existing wood-type ordering in `woods-2`; -- Concrete and Wool slabs and stairs were grouped with the existing shape-based sections instead of being appended after all older entries; -- Explorer Map items were placed immediately after `MAP` in `tools`; -- `SHELF_MUSHROOM` and `RED_SHRUB` were placed near related plant entries in `farms` and `flowers`. - -Placement changes must not alter the classification itself. After reorganizing the entries, compare the state before and after reordering and verify that: - -- the number of newly added items is unchanged; -- every new item remains in the same category; -- every new item retains the same Minecraft data-version guard. - -A useful invariant is the set of `(category, data-version, item)` tuples for the target version: reordering may change line positions, but it must not change that set. - -For example, Minecraft 26.3 added 121 generated item identifiers and removed none compared with 26.2. The update used data version 5023 and classified the new items into existing categories, including Poplar items under `woods-2`, concrete variants under `concretes`, wool/cushion/bed items under `wools`, and explorer-map items under `tools`. The placement was then adjusted according to the rules above without changing the 121-item count, category assignments, or data version. These numbers and data version are historical facts for the 26.3 update only; always derive the corresponding values again for future versions. - -After editing the categories, rerun: +Rerun the generator after category changes: ```shell ./gradlew :box-data-generator:runServer ``` -The goal is for `-uncategorized-items.txt` to exist and be empty. +`-uncategorized-items.txt` must exist and be empty. ## 5. Handle renamed items -Only do this when Minecraft renamed an item identifier. - -Add a resource file named after the Minecraft data version: +If the previous and target lists indicate that an identifier was renamed, add: ```text item-provider/src/main/resources/.txt ``` -Each mapping is: +with mappings in this format: ```text OLD_NAME:NEW_NAME ``` -For example, Minecraft 1.21.9 used: - -```text -CHAIN:IRON_CHAIN -``` - Then: -1. add a corresponding `MCDataVersion` constant in +1. add an `MCDataVersion` constant for that exact data-version boundary in `api/src/main/java/net/okocraft/box/api/util/MCDataVersion.java`; -2. add that constant to `RenamedItems.VERSIONS` in +2. register it in `RenamedItems.VERSIONS` in `item-provider/src/main/java/net/okocraft/box/item/RenamedItems.java`; -3. rerun the data generator so `-new-items.txt` does not incorrectly report renamed items as newly added items; -4. update category entries to preserve the old name before the rename and the new name from the rename data version onward. - -Do not add an `MCDataVersion` constant merely because Minecraft released a new version. Since the June 2026 refactor, constants are only needed when code needs to refer to that exact data-version boundary, such as an item rename migration. - -Minecraft 26.3 had no removed generated identifiers compared with 26.2, so no rename migration was needed in that update. Do not assume this will be true for later versions. - -## 6. Review API-specific breakage - -Minecraft updates can require source changes unrelated to generated items. Typical signals are compilation failures or behavior changes in Paper/Bukkit APIs. +3. update affected category entries using the existing rename syntax when necessary; +4. rerun the generator and confirm the renamed item is not incorrectly reported as new. -Examples from previous updates include: +Do not add an `MCDataVersion` constant for every Minecraft release. Add one only when code needs that exact boundary, such as a rename migration. -- changed Adventure/Paper component APIs; -- changed sound/category APIs; -- changed item metadata APIs; -- behavior changes around projectiles or item types. +## 6. Verify the update -Keep these fixes in the same Minecraft update only when they are required for the target version. - -## 7. Verify - -Run the following checks after the generated data and categories are complete: +Run: ```shell ./gradlew :box-data-generator:runServer ./gradlew build ``` -If local generation is unavailable, perform the equivalent generator checks in the temporary GitHub Actions workflow and download its artifact. +If local generation is unavailable, perform the generator checks in the temporary GitHub Actions workflow and run the normal project CI/build checks. -Verify that: +Verify all of the following: +- `runServer` terminates automatically after generation; - `-uncategorized-items.txt` exists and is empty; -- `-new-items.txt` contains only genuinely new items after known renames are applied; -- after any category-ordering cleanup, the count and set of `(category, data-version, item)` tuples for newly added items are unchanged; -- the generated complete `.txt` and the committed `data-generator/src/main/resources/generated/items/.txt` are identical; -- the previous and target complete lists have been compared for unexpected removals; -- `runServer` exits after generation and the Paper server does not remain running; -- every rename has a migration resource and is registered in `RenamedItems.VERSIONS`; -- the project compiles and tests pass; -- any Paper/Bukkit API breakage has been handled intentionally; -- any temporary GitHub Actions workflow used for generation has been removed from the final branch. - -For a strong equality check between the generated and committed full lists, compare the files byte-for-byte or compare their Git blob hashes. Minecraft 26.3 was verified by matching the generated artifact's complete list with the committed `26.3.txt`. +- `-new-items.txt` contains only genuinely new items after rename handling; +- the generated complete `.txt` is byte-for-byte identical to the committed `data-generator/src/main/resources/generated/items/.txt`; +- removed identifiers from the previous complete list have been explained or handled; +- category ordering cleanup did not change the new items' count, category assignments, or data-version guards; +- every rename migration is registered in `RenamedItems.VERSIONS`; +- the project builds and tests pass; +- any temporary GitHub Actions workflow has been removed. -## Files normally changed +## Files commonly changed -For a straightforward update after the current versioning refactor, expect changes to a subset of: +A normal version update usually changes: ```text -gradle/libs.versions.toml data-generator/build.gradle.kts data-generator/src/main/resources/generated/items/.txt features/category/src/main/resources/default_categories.yml -features/category/src/main/java/net/okocraft/box/feature/category/internal/category/defaults/DefaultCategories.java ``` -When item identifiers are renamed, also expect: +Depending on the update, it may also change: ```text +gradle/libs.versions.toml +features/category/src/main/java/net/okocraft/box/feature/category/internal/category/defaults/DefaultCategories.java api/src/main/java/net/okocraft/box/api/util/MCDataVersion.java item-provider/src/main/java/net/okocraft/box/item/RenamedItems.java item-provider/src/main/resources/.txt ``` -The auto-stop support added during the Minecraft 26.3 update also changed: - -```text -data-generator/src/main/java/net/okocraft/box/datagenerator/Main.java -``` - -That is a one-time data-generator infrastructure change, not a file that should normally change for every Minecraft version. - -Other source files should only change when the new Paper/Bukkit API requires compatibility fixes. - -## Automation boundary - -The following parts are suitable for automation: - -1. update `previousMinecraftVersion` and `minecraftVersion`; -2. run the data generator locally or through a temporary GitHub Actions workflow; -3. copy `.txt` into the committed generated-item directory; -4. compare the previous and target complete item lists; -5. report the contents of `-new-items.txt` and `-uncategorized-items.txt`; -6. run the build and report compilation/test failures; -7. verify that the generator terminates and that the committed complete list matches the generated output. +Other source files should change only when required by Paper/Bukkit API compatibility or another concrete behavior change. -The following parts require evidence-based review rather than blind automation: +## Automation guidance -- assigning new items to categories and placing them consistently with the category's existing ordering; -- deciding whether a new default category should be introduced; -- identifying semantic item renames and migration mappings; -- adapting Box code to Paper/Bukkit API changes. +An automated update can perform the version edits, generation, full-list comparison, generated-file copy, category coverage check, build, and final invariants. -If the requested task includes classification, an automated agent should use the existing category structure and official Minecraft change information to classify and validate the new items instead of stopping at the first judgment call. It should request clarification only when those sources do not provide enough evidence for a defensible decision. +When classification is part of the requested work, it should also classify and place new items using the existing category structure and official Minecraft information. It should stop for clarification only when those sources do not support a defensible classification or rename decision. From 2310766c236f67b98bac774eeb610f950346ac6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=97=E3=82=8D=E3=81=97=E3=82=85=E3=82=93?= <39247022+Siroshun09@users.noreply.github.com> Date: Sat, 3 Oct 2026 20:29:30 +0900 Subject: [PATCH 5/8] docs: require MCDataVersion constants for supported versions --- docs/how-to-update-minecraft-version.md | 58 +++++++++++++++++++------ 1 file changed, 44 insertions(+), 14 deletions(-) diff --git a/docs/how-to-update-minecraft-version.md b/docs/how-to-update-minecraft-version.md index 9e05afbcdd..fd21633962 100644 --- a/docs/how-to-update-minecraft-version.md +++ b/docs/how-to-update-minecraft-version.md @@ -8,7 +8,8 @@ Determine: - the currently committed Minecraft version; - the target Minecraft version; -- a Paper API build compatible with the target version. +- a Paper API build compatible with the target version; +- the Minecraft data version for the target version. Check `gradle/libs.versions.toml`. Renovate may already have updated `paper`; otherwise update it to a compatible build. @@ -63,6 +64,35 @@ The relevant outputs are: Do not reuse a data-version value from an older Minecraft update. +## 3. Update `MCDataVersion` + +Every Minecraft version that Box explicitly supports must have a corresponding constant in: + +```text +api/src/main/java/net/okocraft/box/api/util/MCDataVersion.java +``` + +After confirming the target data version, add the target version constant in the existing chronological order: + +```java +public static final MCDataVersion MC_ = new MCDataVersion(); +``` + +Also review the supported versions between the previously committed version and the target version. If Box already added support for an intermediate Minecraft version but its `MCDataVersion` constant is missing, add that constant as part of the update instead of leaving a gap. + +Confirm each data-version value from the target Minecraft/Paper runtime or another authoritative source. Values from older updates are examples only and must not be reused for future versions. + +For example, PR #615 filled two missing supported-version constants: + +```java +MC_26_2 = 4903 +MC_26_3 = 5023 +``` + +Those values apply only to Minecraft 26.2 and 26.3. + +Adding an `MCDataVersion` constant is independent from item rename handling. Do not add an entry to `RenamedItems.VERSIONS` or create a rename resource unless item identifiers actually changed. + ### If the generator cannot run locally Create a temporary workflow under `.github/workflows/` on the update branch. It should: @@ -77,7 +107,7 @@ Use a workflow-level timeout only as a failure safeguard. Do not make a timed-ou Download the artifact, use it for the update and verification, then delete the temporary workflow before the PR is complete. -## 3. Commit the generated complete list +## 4. Commit the generated complete list Copy: @@ -97,7 +127,7 @@ Compare the previous and target complete lists. Investigate any removed identifi The `-new-items.txt` and `-uncategorized-items.txt` files are review artifacts and are not committed. -## 4. Categorize new items +## 5. Categorize new items Use `-new-items.txt` and `-uncategorized-items.txt` to update: @@ -155,7 +185,7 @@ Rerun the generator after category changes: `-uncategorized-items.txt` must exist and be empty. -## 5. Handle renamed items +## 6. Handle renamed items If the previous and target lists indicate that an identifier was renamed, add: @@ -171,16 +201,14 @@ OLD_NAME:NEW_NAME Then: -1. add an `MCDataVersion` constant for that exact data-version boundary in - `api/src/main/java/net/okocraft/box/api/util/MCDataVersion.java`; -2. register it in `RenamedItems.VERSIONS` in +1. register the already-added version constant in `RenamedItems.VERSIONS` in `item-provider/src/main/java/net/okocraft/box/item/RenamedItems.java`; -3. update affected category entries using the existing rename syntax when necessary; -4. rerun the generator and confirm the renamed item is not incorrectly reported as new. +2. update affected category entries using the existing rename syntax when necessary; +3. rerun the generator and confirm the renamed item is not incorrectly reported as new. -Do not add an `MCDataVersion` constant for every Minecraft release. Add one only when code needs that exact boundary, such as a rename migration. +`RenamedItems.VERSIONS` and `item-provider/src/main/resources/.txt` are rename-specific. Update them only when an item identifier actually changed; they are not required merely because a new Minecraft version is supported. -## 6. Verify the update +## 7. Verify the update Run: @@ -198,8 +226,10 @@ Verify all of the following: - `-new-items.txt` contains only genuinely new items after rename handling; - the generated complete `.txt` is byte-for-byte identical to the committed `data-generator/src/main/resources/generated/items/.txt`; - removed identifiers from the previous complete list have been explained or handled; +- the target Minecraft version has the correct `MCDataVersion` constant; +- supported intermediate Minecraft versions do not have missing `MCDataVersion` constants; - category ordering cleanup did not change the new items' count, category assignments, or data-version guards; -- every rename migration is registered in `RenamedItems.VERSIONS`; +- when renames exist, every rename migration is registered in `RenamedItems.VERSIONS`; - the project builds and tests pass; - any temporary GitHub Actions workflow has been removed. @@ -211,6 +241,7 @@ A normal version update usually changes: data-generator/build.gradle.kts data-generator/src/main/resources/generated/items/.txt features/category/src/main/resources/default_categories.yml +api/src/main/java/net/okocraft/box/api/util/MCDataVersion.java ``` Depending on the update, it may also change: @@ -218,7 +249,6 @@ Depending on the update, it may also change: ```text gradle/libs.versions.toml features/category/src/main/java/net/okocraft/box/feature/category/internal/category/defaults/DefaultCategories.java -api/src/main/java/net/okocraft/box/api/util/MCDataVersion.java item-provider/src/main/java/net/okocraft/box/item/RenamedItems.java item-provider/src/main/resources/.txt ``` @@ -227,6 +257,6 @@ Other source files should change only when required by Paper/Bukkit API compatib ## Automation guidance -An automated update can perform the version edits, generation, full-list comparison, generated-file copy, category coverage check, build, and final invariants. +An automated update can perform the version edits, data-version lookup, `MCDataVersion` constant updates, missing-intermediate-constant checks, generation, full-list comparison, generated-file copy, category coverage check, build, and final invariants. When classification is part of the requested work, it should also classify and place new items using the existing category structure and official Minecraft information. It should stop for clarification only when those sources do not support a defensible classification or rename decision. From 9b8fd9442ce55a0542111fac1aa813ce42b67929 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=97=E3=82=8D=E3=81=97=E3=82=85=E3=82=93?= <39247022+Siroshun09@users.noreply.github.com> Date: Sat, 3 Oct 2026 20:29:52 +0900 Subject: [PATCH 6/8] docs: keep generator fallback with generation steps --- docs/how-to-update-minecraft-version.md | 28 ++++++++++++------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/how-to-update-minecraft-version.md b/docs/how-to-update-minecraft-version.md index fd21633962..ec34d84736 100644 --- a/docs/how-to-update-minecraft-version.md +++ b/docs/how-to-update-minecraft-version.md @@ -64,6 +64,20 @@ The relevant outputs are: Do not reuse a data-version value from an older Minecraft update. +### If the generator cannot run locally + +Create a temporary workflow under `.github/workflows/` on the update branch. It should: + +1. check out the branch; +2. use the repository's current Java/Gradle setup; +3. run `./gradlew :box-data-generator:runServer`; +4. verify that the three generated files exist; +5. upload `data-generator/build/resources/generated-data/` as an artifact. + +Use a workflow-level timeout only as a failure safeguard. Do not make a timed-out `runServer` invocation count as success; the command must terminate normally through auto-stop. + +Download the artifact, use it for the update and verification, then delete the temporary workflow before the PR is complete. + ## 3. Update `MCDataVersion` Every Minecraft version that Box explicitly supports must have a corresponding constant in: @@ -93,20 +107,6 @@ Those values apply only to Minecraft 26.2 and 26.3. Adding an `MCDataVersion` constant is independent from item rename handling. Do not add an entry to `RenamedItems.VERSIONS` or create a rename resource unless item identifiers actually changed. -### If the generator cannot run locally - -Create a temporary workflow under `.github/workflows/` on the update branch. It should: - -1. check out the branch; -2. use the repository's current Java/Gradle setup; -3. run `./gradlew :box-data-generator:runServer`; -4. verify that the three generated files exist; -5. upload `data-generator/build/resources/generated-data/` as an artifact. - -Use a workflow-level timeout only as a failure safeguard. Do not make a timed-out `runServer` invocation count as success; the command must terminate normally through auto-stop. - -Download the artifact, use it for the update and verification, then delete the temporary workflow before the PR is complete. - ## 4. Commit the generated complete list Copy: From 6ec36fc0bcce6bbe99b69f5fb0dc7dce9ba260b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=97=E3=82=8D=E3=81=97=E3=82=85=E3=82=93?= <39247022+Siroshun09@users.noreply.github.com> Date: Sat, 3 Oct 2026 20:32:17 +0900 Subject: [PATCH 7/8] docs: finalize Minecraft update guide --- docs/how-to-update-minecraft-version.md | 210 ++++++------------------ 1 file changed, 46 insertions(+), 164 deletions(-) diff --git a/docs/how-to-update-minecraft-version.md b/docs/how-to-update-minecraft-version.md index ec34d84736..fefe30a221 100644 --- a/docs/how-to-update-minecraft-version.md +++ b/docs/how-to-update-minecraft-version.md @@ -1,36 +1,33 @@ # How to update the Minecraft version -This document describes the workflow for updating Box to a new Minecraft/Paper version using the current repository structure. +Use this procedure when updating Box to a new Minecraft/Paper version. -## 1. Prepare the target version +## 1. Set the target version Determine: -- the currently committed Minecraft version; -- the target Minecraft version; -- a Paper API build compatible with the target version; -- the Minecraft data version for the target version. +- previous and target Minecraft versions; +- a compatible Paper API version; +- the target Minecraft data version. -Check `gradle/libs.versions.toml`. Renovate may already have updated `paper`; otherwise update it to a compatible build. - -Run: +Update `gradle/libs.versions.toml` if Renovate has not already updated Paper, then run: ```shell ./gradlew build ``` -Resolve compilation errors caused by Paper/Bukkit API changes as part of the version update. +Fix any Paper/Bukkit API incompatibilities before continuing. -## 2. Configure and run the data generator +## 2. Generate item data -Edit `data-generator/build.gradle.kts`: +Update `data-generator/build.gradle.kts`: ```kotlin val previousMinecraftVersion = "" val minecraftVersion = "" ``` -`previousMinecraftVersion` must match an existing file: +`previousMinecraftVersion` must have a committed file at: ```text data-generator/src/main/resources/generated/items/.txt @@ -42,72 +39,37 @@ Run: ./gradlew :box-data-generator:runServer ``` -The existing `runServer` configuration enables `net.okocraft.box.datagenerator.auto-stop`, so the server must stop automatically after generation. If the process remains running, treat the generation as failed and fix the auto-stop behavior before continuing. - -Generated files are written to: - -```text -data-generator/build/resources/generated-data/ -``` - -The relevant outputs are: +`runServer` must stop automatically after generation. Its outputs are: ```text -.txt --new-items.txt --uncategorized-items.txt +data-generator/build/resources/generated-data/.txt +data-generator/build/resources/generated-data/-new-items.txt +data-generator/build/resources/generated-data/-uncategorized-items.txt ``` -- `.txt`: complete default-item list for the target version. -- `-new-items.txt`: items not present in the previous version after known rename mappings are applied. -- `-uncategorized-items.txt`: items missing from the default categories. Each line includes the current Minecraft data version; use that generated value when adding version guards. - -Do not reuse a data-version value from an older Minecraft update. - -### If the generator cannot run locally - -Create a temporary workflow under `.github/workflows/` on the update branch. It should: - -1. check out the branch; -2. use the repository's current Java/Gradle setup; -3. run `./gradlew :box-data-generator:runServer`; -4. verify that the three generated files exist; -5. upload `data-generator/build/resources/generated-data/` as an artifact. - -Use a workflow-level timeout only as a failure safeguard. Do not make a timed-out `runServer` invocation count as success; the command must terminate normally through auto-stop. - -Download the artifact, use it for the update and verification, then delete the temporary workflow before the PR is complete. +If the generator cannot run locally, create a temporary GitHub Actions workflow that runs the same task, verifies these files, and uploads the generated directory as an artifact. Remove the workflow after verification. A timeout is a failure safeguard, not a successful substitute for normal auto-stop. ## 3. Update `MCDataVersion` -Every Minecraft version that Box explicitly supports must have a corresponding constant in: +Every Minecraft version supported by Box must have a constant in: ```text api/src/main/java/net/okocraft/box/api/util/MCDataVersion.java ``` -After confirming the target data version, add the target version constant in the existing chronological order: +Add the target version in chronological order using the data version confirmed from the target runtime or another authoritative source: ```java public static final MCDataVersion MC_ = new MCDataVersion(); ``` -Also review the supported versions between the previously committed version and the target version. If Box already added support for an intermediate Minecraft version but its `MCDataVersion` constant is missing, add that constant as part of the update instead of leaving a gap. - -Confirm each data-version value from the target Minecraft/Paper runtime or another authoritative source. Values from older updates are examples only and must not be reused for future versions. - -For example, PR #615 filled two missing supported-version constants: +Also check versions between the previous and target versions and fill any missing constants for versions Box already supports. -```java -MC_26_2 = 4903 -MC_26_3 = 5023 -``` +For reference, Minecraft 26.2 and 26.3 use 4903 and 5023 respectively. These are examples only; determine the correct data version for every future update. -Those values apply only to Minecraft 26.2 and 26.3. +This step is independent of item renames. Do not update `RenamedItems.VERSIONS` or rename resources unless identifiers actually changed. -Adding an `MCDataVersion` constant is independent from item rename handling. Do not add an entry to `RenamedItems.VERSIONS` or create a rename resource unless item identifiers actually changed. - -## 4. Commit the generated complete list +## 4. Commit the generated list and handle renames Copy: @@ -121,11 +83,16 @@ to: data-generator/src/main/resources/generated/items/.txt ``` -If generation ran in GitHub Actions, copy the file from the downloaded artifact instead. +Compare the previous and target complete lists. Investigate every removed identifier. + +If an identifier was renamed: -Compare the previous and target complete lists. Investigate any removed identifiers because they may indicate item renames or other compatibility changes. +1. add `item-provider/src/main/resources/.txt` with `OLD_NAME:NEW_NAME` mappings; +2. register the corresponding `MCDataVersion` constant in `RenamedItems.VERSIONS`; +3. update affected category entries using the existing rename syntax; +4. rerun the generator and confirm the renamed item is not reported as new. -The `-new-items.txt` and `-uncategorized-items.txt` files are review artifacts and are not committed. +Do not modify rename resources or `RenamedItems.VERSIONS` when there are no identifier renames. ## 5. Categorize new items @@ -135,80 +102,27 @@ Use `-new-items.txt` and `-uncategorized-items.txt` to update: features/category/src/main/resources/default_categories.yml ``` -Add newly introduced items with the data version emitted by the generator: +New items must use the target data version: ```yaml - : ``` -Classify items using, in order: +Classify from existing Box categories, similar item families, and official Minecraft change information. If these provide a defensible classification, complete and verify it; ask only when they do not. -1. existing Box categories and the placement of similar items; -2. item-family and naming patterns; -3. official Minecraft release notes or changelogs. +Keep each item near related existing entries instead of appending all new items at the category end. Follow the category's existing ordering, for example by wood family, shape/type, base item, or related plants. -If the task includes classification, continue through classification and validation when these sources provide a defensible answer. Ask for clarification only when they do not. - -Items that should not be available as normal Box items belong in the existing `unavailable` category rather than being left uncategorized. - -If the release introduces a group that genuinely requires a new default category, update both: +If a genuinely new category is needed, also update: ```text -features/category/src/main/resources/default_categories.yml features/category/src/main/java/net/okocraft/box/feature/category/internal/category/defaults/DefaultCategories.java ``` -### Preserve category ordering - -Do not append all new items to the end of a category. Follow the local ordering already used in that category and place each item near related existing entries. - -Current ordering patterns include: - -- wood families in `woods-2`: keep each new wood type aligned with the corresponding planks, slabs, stairs, logs, wood, leaves, saplings, signs, boats, and other wood variants; -- `concretes` and `wools`: group variants by shape/type, such as slabs together and stairs together; -- `tools`: place specialized map items immediately after `MAP`; -- plant-related categories such as `farms` and `flowers`: place new plants near the most closely related existing plants. - -Reordering must not change classification. After placement cleanup, verify that the newly added items have exactly the same: - -- item count; -- category assignments; -- data-version guards. - -Equivalently, the set of `(category, data-version, item)` tuples for the target version must be unchanged by reordering. - -Rerun the generator after category changes: - -```shell -./gradlew :box-data-generator:runServer -``` - -`-uncategorized-items.txt` must exist and be empty. - -## 6. Handle renamed items - -If the previous and target lists indicate that an identifier was renamed, add: - -```text -item-provider/src/main/resources/.txt -``` - -with mappings in this format: - -```text -OLD_NAME:NEW_NAME -``` - -Then: - -1. register the already-added version constant in `RenamedItems.VERSIONS` in - `item-provider/src/main/java/net/okocraft/box/item/RenamedItems.java`; -2. update affected category entries using the existing rename syntax when necessary; -3. rerun the generator and confirm the renamed item is not incorrectly reported as new. +After ordering changes, the set of `(category, data-version, item)` tuples for the new items must be unchanged. -`RenamedItems.VERSIONS` and `item-provider/src/main/resources/.txt` are rename-specific. Update them only when an item identifier actually changed; they are not required merely because a new Minecraft version is supported. +Rerun the generator. `-uncategorized-items.txt` must be empty. -## 7. Verify the update +## 6. Verify Run: @@ -217,46 +131,14 @@ Run: ./gradlew build ``` -If local generation is unavailable, perform the generator checks in the temporary GitHub Actions workflow and run the normal project CI/build checks. - -Verify all of the following: - -- `runServer` terminates automatically after generation; -- `-uncategorized-items.txt` exists and is empty; -- `-new-items.txt` contains only genuinely new items after rename handling; -- the generated complete `.txt` is byte-for-byte identical to the committed `data-generator/src/main/resources/generated/items/.txt`; -- removed identifiers from the previous complete list have been explained or handled; -- the target Minecraft version has the correct `MCDataVersion` constant; -- supported intermediate Minecraft versions do not have missing `MCDataVersion` constants; -- category ordering cleanup did not change the new items' count, category assignments, or data-version guards; -- when renames exist, every rename migration is registered in `RenamedItems.VERSIONS`; -- the project builds and tests pass; -- any temporary GitHub Actions workflow has been removed. - -## Files commonly changed - -A normal version update usually changes: - -```text -data-generator/build.gradle.kts -data-generator/src/main/resources/generated/items/.txt -features/category/src/main/resources/default_categories.yml -api/src/main/java/net/okocraft/box/api/util/MCDataVersion.java -``` - -Depending on the update, it may also change: - -```text -gradle/libs.versions.toml -features/category/src/main/java/net/okocraft/box/feature/category/internal/category/defaults/DefaultCategories.java -item-provider/src/main/java/net/okocraft/box/item/RenamedItems.java -item-provider/src/main/resources/.txt -``` - -Other source files should change only when required by Paper/Bukkit API compatibility or another concrete behavior change. - -## Automation guidance - -An automated update can perform the version edits, data-version lookup, `MCDataVersion` constant updates, missing-intermediate-constant checks, generation, full-list comparison, generated-file copy, category coverage check, build, and final invariants. +Confirm: -When classification is part of the requested work, it should also classify and place new items using the existing category structure and official Minecraft information. It should stop for clarification only when those sources do not support a defensible classification or rename decision. +- `runServer` exits normally; +- the uncategorized file is empty; +- the new-items file contains only genuinely new identifiers; +- the generated `.txt` exactly matches the committed file; +- every removed identifier is explained or migrated; +- `MCDataVersion` contains the target and any missing intermediate supported versions; +- rename resources and `RenamedItems.VERSIONS` are updated only when renames exist; +- category ordering did not change item count, category, or data-version guards; +- tests pass and any temporary workflow is removed. From 7dcb036a8fd684b26a4c076ee56737678a354dd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=81=97=E3=82=8D=E3=81=97=E3=82=85=E3=82=93?= <39247022+Siroshun09@users.noreply.github.com> Date: Sat, 3 Oct 2026 20:32:53 +0900 Subject: [PATCH 8/8] docs: clarify final Minecraft update steps --- docs/how-to-update-minecraft-version.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to-update-minecraft-version.md b/docs/how-to-update-minecraft-version.md index fefe30a221..768b0e83c9 100644 --- a/docs/how-to-update-minecraft-version.md +++ b/docs/how-to-update-minecraft-version.md @@ -89,7 +89,7 @@ If an identifier was renamed: 1. add `item-provider/src/main/resources/.txt` with `OLD_NAME:NEW_NAME` mappings; 2. register the corresponding `MCDataVersion` constant in `RenamedItems.VERSIONS`; -3. update affected category entries using the existing rename syntax; +3. update affected categories as `OLD_NAME;:NEW_NAME`; 4. rerun the generator and confirm the renamed item is not reported as new. Do not modify rename resources or `RenamedItems.VERSIONS` when there are no identifier renames. @@ -108,7 +108,7 @@ New items must use the target data version: - : ``` -Classify from existing Box categories, similar item families, and official Minecraft change information. If these provide a defensible classification, complete and verify it; ask only when they do not. +Classify from existing Box categories, similar item families, and official Minecraft change information. If these provide a defensible classification, complete and verify it; ask only when they do not. Items that should not be available normally belong in `unavailable`. Keep each item near related existing entries instead of appending all new items at the category end. Follow the category's existing ordering, for example by wood family, shape/type, base item, or related plants.