compare-version-modules

name	compare-version-modules
description	Compare two server-platform adaptation modules of the same platform but different Minecraft/game versions (e.g. forge-1.21.5 vs forge-1.21.8), surfacing only the real API / 写法 differences by normalizing away package-name and version-string noise. Use when the user asks to 对比/比较/diff two version modules, find what changed between two `<platform>-<version>` directories (forge/neoforge/fabric/spigot/folia), or understand how to port an adaptation from one game version to the next.
metadata	{"internal":true}

Compare version modules

Adaptation modules for different game versions of the same platform do the same job with slightly different code. This skill isolates the meaningful deltas (API renames, signature changes, new imports, build-config bumps) from the mechanical noise (package names and version numbers that differ in every file).

Quick start

Run the bundled script with the two module directory paths. Modules now live under their platform folder (fabric/, forge/, neoforge/, bukkit/), so pass the platform-prefixed path:

bash <skill-dir>/scripts/compare.sh forge/forge-1.21.5 forge/forge-1.21.8

(The script derives the package token from the directory's basename, so the platform-folder prefix does not affect normalization.)

It pairs files across the two modules, normalizes each module's package token, directory name, and version string into shared placeholders, then prints a per-file diff plus a summary line. Files that are identical after normalization are omitted; files present in only one module are flagged ONLY IN ....

Convention it relies on

Directory <platform>/<platform>-<version> ↔ java package net.opanel.<platform>_<ver>, where the package token is the module directory's basename with - and . turned into _:

• forge-1.21.5 → forge_1_21_5
• spigot-1.16.1 → spigot_1_16_1
• neoforge-1.21.3 → neoforge_1_21_3

This holds for forge / neoforge / fabric / spigot / folia in this repo.

Workflow

1. Run scripts/compare.sh <platform>/<older> <platform>/<newer> from the repo root.
2. Read the diff. Each ===== <path> ===== block is one changed file.
3. Group the findings for the user, e.g.:
   • Build config — gradle.properties (version range, loader version), build.gradle (new repos/deps), pack.mcmeta (pack_format).
   • API changes — renamed/moved imports, changed method signatures, replaced types (e.g. GameProfile → NameAndId).
   • New behavior — added listeners, fields, null guards, newly-implemented interfaces.
4. Note knock-on changes: a constructor signature change in one file usually forces edits at every call site — call those out together.
5. Skip files reported only as version-string/package differences; the script already removed those, so anything left is a genuine difference worth reporting.

Notes

• The right bound of minecraft_version_range (the next version) is a real difference, not noise, so it is intentionally shown.
• If a module pair lives outside the repo root, pass full/relative paths: compare.sh path/to/forge-1.21.8 path/to/forge-1.21.9 (any path works; only the basename matters).
• The script reads files only; it never edits. Safe to run anytime.