Versioning Guide

Purpose: Document versioning strategy and provide guidance for version updates in Chrono Dawn mod.

When to use: When updating mod version, preparing for release, or understanding version numbering.

---

Semantic Versioning Overview

Chrono Dawn follows Semantic Versioning 2.0.0 (https://semver.org/).

Version Format

<major>.<minor>.<patch>-<prerelease>+<buildmetadata>

Examples:

• 0.2.0-beta+1.21.1-fabric - Beta version for Minecraft 1.21.1 (Fabric)
• 1.0.0+1.21.1-neoforge - Stable release for Minecraft 1.21.1 (NeoForge)
• 1.2.3-rc.1+1.21.2-fabric - Release Candidate 1 for Minecraft 1.21.2 (Fabric)

Components

1. Version Number (major.minor.patch):

   • major: Incompatible API changes (e.g., 0.x.x → 1.0.0)
   • minor: New features, backward-compatible (e.g., 1.0.0 → 1.1.0)
   • patch: Bug fixes, backward-compatible (e.g., 1.1.0 → 1.1.1)

2. Prerelease Identifier (optional, -<identifier>):

   • Separated by hyphen -
   • Examples: -alpha, -beta, -rc.1
   • Indicates unstable/pre-release version
   • Removed for stable releases

3. Build Metadata (+<minecraft-version>-<loader>):

   • Separated by plus +
   • Format: +<minecraft_version>-<fabric|neoforge>
   • Example: +1.21.1-fabric
   • Automatically appended by build system

---

Chrono Dawn Versioning Strategy

Development vs. Release Versions

Development (during feature implementation):

mod_version=0.2.0-beta

Builds to: chronodawn-0.2.0-beta+1.21.1-fabric.jar

Release (when publishing):

mod_version=0.2.0

Builds to: chronodawn-0.2.0+1.21.1-fabric.jar

Prerelease Identifiers

Use appropriate identifiers based on development stage:

• -alpha: Early development, major features incomplete

  • Example: 0.2.0-alpha
  • Use case: Initial implementation of new dimension

• -beta: Feature-complete, testing in progress

  • Example: 0.2.0-beta
  • Use case: All bosses implemented, playtesting phase

• -rc.1, -rc.2, etc.: Release Candidate

  • Example: 1.0.0-rc.1
  • Use case: Final testing before stable release, no new features

• No identifier: Stable release

  • Example: 1.0.0
  • Use case: Production-ready, fully tested

Version Increment Guide

Change Type	Example	When to Use
0.1.0 → 0.2.0	New major features (new dimension area, new boss system)
0.2.0 → 0.2.1	Bug fixes only
0.9.0 → 1.0.0	First stable release
1.0.0 → 2.0.0	Breaking changes (incompatible with old saves)

---

Build System Integration

gradle.properties

Define only the version number and prerelease identifier:

mod_version=0.2.0-beta

Do NOT include Minecraft version or loader name here.

Build Scripts

fabric/build.gradle (line 86):

archiveVersion = "${rootProject.mod_version}+${rootProject.minecraft_version}-fabric"

neoforge/build.gradle (line 98):

archiveVersion = "${rootProject.mod_version}+${rootProject.minecraft_version}-neoforge"

These scripts automatically append +1.21.1-fabric or +1.21.1-neoforge.

Resulting JAR Names

From mod_version=0.2.0-beta:

• Fabric: chronodawn-0.2.0-beta+1.21.1-fabric.jar
• NeoForge: chronodawn-0.2.0-beta+1.21.1-neoforge.jar
• Common: common-0.2.0-beta.jar

---

Version Update Procedure

Files to Update

When changing mod_version in gradle.properties, also update:

1. gradle.properties (line 6)

   mod_version=X.Y.Z-prerelease
   

2. README.md (lines 81-83, 209, 220)

   • Build output file names
   • Installation instructions

3. docs/player_guide.md (lines 78-79)

   • Download file names

4. docs/developer_guide.md (lines 235, 274-276)

   • gradle.properties example
   • Build output file names

5. fabric.mod.json and neoforge.mods.toml

   • Use ${version} placeholder (no manual update needed)

Version Update Checklist

• Update gradle.properties with new version
• Update all documentation with correct JAR names (include +1.21.1)
• Verify version format follows Semantic Versioning
• For release: Remove prerelease identifier (e.g., -beta)
• Test build: ./gradlew clean build
• Verify JAR names match documentation

---

Common Patterns

Preparing Next Version (Development)

# Start development on 0.3.0
mod_version=0.3.0-alpha

Pre-Release Testing

# Feature-complete, ready for testing
mod_version=0.3.0-beta

Release Candidate

# Final testing before release
mod_version=0.3.0-rc.1

Stable Release

# Production release
mod_version=0.3.0

Hotfix Release

# Critical bug fix for 0.3.0
mod_version=0.3.1

---

Examples by Scenario

Scenario 1: Starting Development on 0.2.0

Current: 0.1.0 (stable)
Change to: 0.2.0-alpha
Reason: Beginning work on new features

Scenario 2: Entering Beta Phase

Current: 0.2.0-alpha
Change to: 0.2.0-beta
Reason: All features implemented, testing phase

Scenario 3: Preparing Release

Current: 0.2.0-beta
Change to: 0.2.0-rc.1
Reason: Final testing before release

Scenario 4: Stable Release

Current: 0.2.0-rc.1
Change to: 0.2.0
Reason: Release candidate passed testing

Scenario 5: Bug Fix Release

Current: 0.2.0 (stable)
Change to: 0.2.1
Reason: Critical bug found, needs hotfix

---

Automated Version Update

Use the update-version command to automate version updates:

/update-version 0.3.0-beta

This will:

1. Update gradle.properties
2. Update all documentation files with correct JAR names
3. Verify version format

---

Reference

• Semantic Versioning Spec: https://semver.org/
• Current Version: Check gradle.properties line 6
• Version History: See git tags and CHANGELOG.md (if exists)

---

Last Updated: 2026-01-01 Maintained by: Chrono Dawn Development Team