From 2eebc328502e2cfb9e32ce4e55dcce6ecfff0ea0 Mon Sep 17 00:00:00 2001 From: JohnBraham Date: Mon, 17 Aug 2026 23:08:03 +0100 Subject: [PATCH] Adopt target-qualified four-component version --- CHANGELOG.txt | 5 +- README.md | 7 +- docs/AGENTS.md | 1 + docs/README.md | 1 + docs/VERSIONS.md | 203 ++++++++++++++++++ gradle.properties | 2 +- .../orespawn/compat/LegacyOs3Bridge.java | 2 +- src/main/java/cyano/orespawn/OreSpawn.java | 2 +- .../zone/moddev/mc/orespawn/OreSpawn.java | 2 +- .../LegacyMineralogyProfileMigration.java | 2 +- .../worldgen/LegacyOs3ProfileMigration.java | 2 +- 11 files changed, 220 insertions(+), 9 deletions(-) create mode 100644 docs/VERSIONS.md diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 96537f12..213c5dca 100644 --- a/CHANGELOG.txt +++ b/CHANGELOG.txt @@ -1,6 +1,7 @@ -Version 4.0.6 +Version 4.0.6.110021 -* Port OreSpawn 4.0.6 to Minecraft 1.10.2 and Forge 12.18.3.2511 using Java 8. +* Adopt target-qualified four-component versions so Minecraft and loader compatibility can be identified from the mod version. +* Port OreSpawn 4.0.6.110021 to Minecraft 1.10.2 and Forge 12.18.3.2511 using Java 8. * Add deprecated OS1 and OS3 binary/configuration compatibility bridges for OreSpawn 1.1 and 3.2.2 consumers, translating plugins and registrations into one deduplicated OS4 scheduler with atomic backups and an idempotent report. diff --git a/README.md b/README.md index dea1bf7c..6cc1877e 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,10 @@ It gives mods and modpacks one place to configure ores, deposit shapes, optional rock strata and geomes, provider-owned underground fluid deposits, biome palettes and world materials, flat bedrock, and bounded ore retrogen. +This branch builds target-qualified version `4.0.6.110021`: the OreSpawn 4.0.6 +feature set for Minecraft 1.10.2 and Forge. See the +[versioning policy](docs/VERSIONS.md) for the encoding and release convention. + Its deprecated compatibility layer imports OreSpawn 1 and OreSpawn 3 configuration and keeps existing legacy consumer jars working while translating their rules into the OreSpawn 4 scheduler. It preserves ranged legacy block budgets, @@ -92,6 +96,7 @@ Start with: - [Provider JSON guide](docs/PROVIDERS.md) - [Java API guide](docs/API.md) - [Biome and world-material guide](docs/BIOMES.md) +- [Versioning and release policy](docs/VERSIONS.md) - [Schemas and examples](docs/README.md) The full documentation bundle is packaged under `META-INF/orespawn/docs/` and @@ -99,7 +104,7 @@ exported to `config/orespawn-guide/` without overwriting existing files. ## Building -Use Java 8 from the repository root (the local validation JDK is 1.8.0_221): +Use a Java 8 JDK from the repository root: ```powershell .\gradlew.bat clean build javadoc --no-daemon diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 5c7486a7..04e7b789 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -12,4 +12,5 @@ Use the focused guides for implementation details: - [BIOMES.md](BIOMES.md) and [DIMENSIONS.md](DIMENSIONS.md) for world integration; - [TEMPLATES.md](TEMPLATES.md) for selectable world styles; - [CONFIGURATION.md](CONFIGURATION.md) for configuration behavior; +- [VERSIONS.md](VERSIONS.md) for the shared four-component target-qualified versioning and branch-release convention; - [README.md](README.md) for schemas, examples, and the complete documentation index. diff --git a/docs/README.md b/docs/README.md index e63cf93c..e0e46029 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,6 +17,7 @@ Choose the guide that matches what you are doing: - [Dimensions](DIMENSIONS.md) - [Migration](MIGRATION.md) - [Troubleshooting](TROUBLESHOOTING.md) +- [Versioning and release identities](VERSIONS.md) - [Compact instructions for coding agents](AGENTS.md) Validated examples are in `examples/`; JSON Schemas are in `schemas/`. diff --git a/docs/VERSIONS.md b/docs/VERSIONS.md new file mode 100644 index 00000000..ecee8a69 --- /dev/null +++ b/docs/VERSIONS.md @@ -0,0 +1,203 @@ +# Mod Versioning Policy + +This document defines how versions are assigned to MMD mods and how an exact +Minecraft and loader target is encoded in a release version. + +## Version format + +Mod versions use four numeric components: + +```text +Major.Minor.Bug.Target +``` + +The first three components describe the functional release. For example, +OreSpawn `4.0.6` means major version 4, minor version 0, and bug revision 6. + +The fourth component identifies the Minecraft and loader target. A complete +release version such as `4.0.6.120061` therefore identifies both the OreSpawn +4.0.6 feature set and its Minecraft 1.20.6 Forge build. + +This is an expanded, Maven-compatible versioning convention. It is not strict +Semantic Versioning 2.0, which defines exactly three numeric core components. + +When the Major or Minor component increases, the functional components to its +right reset to zero. The Target component is then appended for the build being +released. For example: + +```text +4.0.6.120061 -> 4.1.0.120061 +4.1.3.120061 -> 5.0.0.120061 +``` + +## Target component + +The Target component is deterministic and is not another feature or bug +sequence number. + +To calculate it: + +1. Normalize the Minecraft version to `major.minor.patch`, using zero when the + patch component is omitted. +2. Concatenate the Minecraft major number without padding, the minor number as + two digits, the patch number as two digits, and the one-digit loader code. +3. Use loader code `1` for Forge and `2` for NeoForge. + +The component can be decoded from right to left: one loader digit, two patch +digits, two minor digits, and all remaining digits for the Minecraft major +version. + +Examples: + +| Minecraft | Loader | Target | Full OreSpawn 4.0.6 version | +| --- | --- | ---: | --- | +| 1.10.2 | Forge | `110021` | `4.0.6.110021` | +| 1.12.2 | Forge | `112021` | `4.0.6.112021` | +| 1.13.2 | Forge | `113021` | `4.0.6.113021` | +| 1.20.6 | Forge | `120061` | `4.0.6.120061` | +| 1.21.11 | Forge | `121111` | `4.0.6.121111` | +| 26.1.2 | Forge | `2601021` | `4.0.6.2601021` | +| 26.2 | Forge | `2602001` | `4.0.6.2602001` | +| 26.2 | NeoForge | `2602002` | `4.0.6.2602002` | + +Historical MMD releases may also have four numeric components but may have used +the fourth component differently. This policy applies prospectively; it does +not reinterpret an old release number. + +## Major version + +Increase the **Major** number for a large-scale change, paradigm shift, or +breaking change that moves the mod forward in a fundamental way. + +Examples include: + +- Mineralogy 6 no longer containing its own world generation engine, unlike + Mineralogy 5. +- OreSpawn 4 gaining a complete terrain generation engine, including strata, + unlike OreSpawn 3. + +Compatibility adaptations required to support another Minecraft or loader +version do not by themselves require a major version increase when the mod's +supported behaviour and public contracts remain equivalent. + +## Minor version + +Increase the **Minor** number for a new feature or a significant change to +existing behaviour that does not justify a new major generation. + +Examples include: + +- adding a new player-usable block or other substantial feature; +- substantially overhauling a world-generation engine; +- making a significant fix or adjustment that materially changes how a major + part of the mod behaves. + +## Bug version + +Increase the **Bug** number for a bug fix or a very small feature that does not +materially change the mod's design. + +Examples include: + +- correcting a generation defect; +- fixing a user interface or compatibility problem; +- adding or correcting a language file translation; +- making a small documentation or configuration improvement that warrants a + release. + +This component is sometimes called the patch number in other versioning +systems. MMD uses the name **Bug** to make its intended purpose explicit. + +## Ports to new Minecraft versions + +Porting a mod to a new Minecraft version does not automatically change the +functional `Major.Minor.Bug` version. Functionally equivalent ports share those +first three components, while their complete versions have different Target +components. + +For example: + +```text +Minecraft 26.1.2 / Forge / OreSpawn 4.0.6.2601021 +Minecraft 26.2 / Forge / OreSpawn 4.0.6.2602001 +Minecraft 26.2 / NeoForge / OreSpawn 4.0.6.2602002 +``` + +Target-specific implementation details may differ internally where Minecraft +or its mod loader requires them. Those adaptations do not change the functional +version when users and integrations receive the same supported behaviour. + +If a port also introduces a feature or fix that changes the functional release, +the first three components must be assessed using the Major, Minor, and Bug +rules above. The Target component always identifies the build's actual +Minecraft and loader target. + +## Branch-specific fixes and skipped numbers + +Functional version numbers are allocated across the mod as a whole and must +not be reused for unrelated change sets on different Minecraft branches. The +same `Major.Minor.Bug` may be shared by functionally equivalent ports. + +If a released branch receives a bug fix that other branches do not require, +only the affected branch's Bug number is incremented. For example, Forge +1.13.2 may move from `4.0.6.113021` to `4.0.7.113021` while unaffected branches +remain on their target-qualified 4.0.6 versions. + +If a different branch later receives a separate fix, it uses the next unused +Bug number, such as `4.0.8`, even if the `4.0.7` fix was not applicable to it. +A branch may therefore legitimately skip functional version numbers. + +This provides three useful guarantees: + +1. A functional version is not used to describe two unrelated change sets. +2. A higher functional version identifies a later change in the mod's release + history. +3. The Target component identifies the exact Minecraft and loader build without + overloading the functional version. + +A higher functional version on another Minecraft branch does **not** +necessarily mean it contains every lower-numbered branch-specific fix. Some +fixes are relevant only to a particular Minecraft or loader implementation. + +## Dependency ranges + +Dependencies should normally express the compatible functional release range. +For example, Maven-style range `[4.0.6,5.0.0)` deliberately accepts all +target-qualified OreSpawn 4.0.6 builds while excluding OreSpawn 5. + +Consumers must still declare their supported Minecraft version and loader in +their own metadata. The Target component makes that compatibility visible; it +does not replace loader-level compatibility checks. + +## Release and pull-request documentation + +Because maintained branches can legitimately contain different fixes, the +version number alone is not a substitute for release notes. + +Every release and pull request should state: + +- the Minecraft version and loader it targets; +- the complete four-component version and its functional `Major.Minor.Bug`; +- the features and fixes actually included; +- any fixes from nearby versions that are not applicable to that branch; +- whether the change is functionally equivalent to another maintained branch; +- any migration, compatibility, or configuration considerations for users. + +## Decision summary + +When assigning a version, ask the following questions in order: + +1. Is this a fundamental or breaking new generation of the mod? Increase + **Major**. +2. Is this a substantial feature or significant behavioural overhaul? Increase + **Minor**. +3. Is this a bug fix or very small feature? Increase **Bug**, using the next + unused number across the mod. +4. Is this only a functionally equivalent Minecraft or loader port? Keep the + existing `Major.Minor.Bug`. +5. Calculate and append the Target component for the exact Minecraft and loader + build. + +The objective is to make versions useful to players, pack developers, mod +integrators, release automation, and support teams while allowing each +maintained Minecraft branch to receive only the changes it actually needs. diff --git a/gradle.properties b/gradle.properties index 8e6cd57e..10881f9a 100644 --- a/gradle.properties +++ b/gradle.properties @@ -13,7 +13,7 @@ mapping_version=stable_29 mod_id=orespawn mod_name=MMD OreSpawn mod_license=LGPL-2.1 -mod_version=4.0.6 +mod_version=4.0.6.110021 mod_group_id=zone.moddev.mc.orespawn mod_authors=SkyBlade1978, dshadowwolf, the MMD Team mod_description=Configurable, provider-driven terrain, ore, and deposit generation. diff --git a/src/main/java/com/mcmoddev/orespawn/compat/LegacyOs3Bridge.java b/src/main/java/com/mcmoddev/orespawn/compat/LegacyOs3Bridge.java index 61f2eafe..5687f6f4 100644 --- a/src/main/java/com/mcmoddev/orespawn/compat/LegacyOs3Bridge.java +++ b/src/main/java/com/mcmoddev/orespawn/compat/LegacyOs3Bridge.java @@ -985,7 +985,7 @@ private static void writeHumanUpgradeReport(Path destination) throws IOException } } List lines = new ArrayList<>(); - lines.add("OreSpawn 4.0.6 Upgrade Report"); + lines.add("OreSpawn 4.0.6.110021 Upgrade Report"); lines.add("================================"); lines.add(""); lines.add("RESULT: Legacy OreSpawn configuration was consumed and translated for OS4."); diff --git a/src/main/java/cyano/orespawn/OreSpawn.java b/src/main/java/cyano/orespawn/OreSpawn.java index 0ea2eda2..a01e8b89 100644 --- a/src/main/java/cyano/orespawn/OreSpawn.java +++ b/src/main/java/cyano/orespawn/OreSpawn.java @@ -19,7 +19,7 @@ public class OreSpawn { public static OreSpawn INSTANCE; public static final String MODID = "orespawn"; public static final String NAME = "OreSpawn"; - public static final String VERSION = "4.0.6"; + public static final String VERSION = "4.0.6.110021"; public static final List oreSpawnConfigFiles = new ArrayList<>(); public static final List additionalStoneBlocks = new ArrayList<>(); public static boolean disableVanillaOreGen; diff --git a/src/main/java/zone/moddev/mc/orespawn/OreSpawn.java b/src/main/java/zone/moddev/mc/orespawn/OreSpawn.java index 2b23e665..d6d86457 100644 --- a/src/main/java/zone/moddev/mc/orespawn/OreSpawn.java +++ b/src/main/java/zone/moddev/mc/orespawn/OreSpawn.java @@ -52,7 +52,7 @@ public class OreSpawn { public static final String MODID = "orespawn"; public static final String NAME = "OreSpawn"; - public static final String VERSION = "4.0.6"; + public static final String VERSION = "4.0.6.110021"; private static final Logger LOGGER = LogManager.getLogger(); diff --git a/src/main/java/zone/moddev/mc/orespawn/worldgen/LegacyMineralogyProfileMigration.java b/src/main/java/zone/moddev/mc/orespawn/worldgen/LegacyMineralogyProfileMigration.java index bd9ec5f4..4e7acc66 100644 --- a/src/main/java/zone/moddev/mc/orespawn/worldgen/LegacyMineralogyProfileMigration.java +++ b/src/main/java/zone/moddev/mc/orespawn/worldgen/LegacyMineralogyProfileMigration.java @@ -125,7 +125,7 @@ private static void writeUpgradeReport(Path worldRoot, Path configDirectory, } List lines = new ArrayList<>(); - lines.add("OreSpawn 4.0.6 Upgrade Report"); + lines.add("OreSpawn 4.0.6.110021 Upgrade Report"); lines.add("================================"); lines.add(""); lines.add("RESULT: Existing Mineralogy " + mineralogyVersion diff --git a/src/main/java/zone/moddev/mc/orespawn/worldgen/LegacyOs3ProfileMigration.java b/src/main/java/zone/moddev/mc/orespawn/worldgen/LegacyOs3ProfileMigration.java index bf6d2679..45082f20 100644 --- a/src/main/java/zone/moddev/mc/orespawn/worldgen/LegacyOs3ProfileMigration.java +++ b/src/main/java/zone/moddev/mc/orespawn/worldgen/LegacyOs3ProfileMigration.java @@ -65,7 +65,7 @@ private static void writeInitialUpgradeReport(Path configDirectory, boolean forceRetrogen, boolean flatBedrock, boolean retrogenBedrock, int bedrockLayers) throws IOException { String newline = System.lineSeparator(); - String text = "OreSpawn 4.0.6 Upgrade Report" + newline + String text = "OreSpawn 4.0.6.110021 Upgrade Report" + newline + "================================" + newline + newline + "RESULT: Legacy OreSpawn settings were imported into the OS4 profile." + newline + "- Manage vanilla ores: " + manageVanilla + newline