Skip to content

Semantic Versioning (SemVer) Contract

Scope: Repository-wide versioning policy, public API definition, internal boundary classification, and binary compatibility commitments. Related: DEPRECATION_POLICY.md, ARCHITECTURE.md, ADR-011, ADR-094.

1. SemVer 2.0.0 Commitment

RTP adheres to Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH):

  • MAJOR version bump (X.0.0):
  • Breaking changes to the public API contracts (rtp-api and SPI framework interfaces).
  • Removal of previously deprecated public API methods, classes, or interfaces.
  • Incompatible changes to core configuration schema syntax requiring manual operator migration.
  • Dropping support for previously tested Minecraft LTS/stable lines or raising the minimum Java runtime baseline.
  • MINOR version bump (X.Y.0):
  • Additions of new backwards-compatible public API methods, interfaces, or SPI hooks.
  • New platform adapter support or new optional subsystems (e.g. proxy backends, new region shapes).
  • Introduction of deprecation notices (@Deprecated(forRemoval = true)) for public API elements.
  • Backwards-compatible configuration additions and migrations.
  • PATCH version bump (X.Y.Z):
  • Backwards-compatible bug fixes, performance optimizations, and documentation updates.
  • Point-release compatibility shims for minor Minecraft or server platform updates that do not alter the public API contract.
  • No changes to public API signatures or breaking configuration defaults.

2. Public API vs. Internal Code Boundary

To make compatibility guarantees actionable and auditable, the codebase is strictly segregated into Public API (governed by SemVer guarantees) and Internal Implementation (subject to change without breaking SemVer).

2.1 Public API Surface (SemVer-Guaranteed)

The public API is designed for third-party addon developers, external integrations, and platform bridge authors. The following modules and packages constitute the public API:

  1. rtp-api (io.github.dailystruggle.rtp.api.*):
  2. Public interfaces: RTPWorld, RTPPlayer, RTPLocation, RTPChunk, RTPScheduler, RTPRegion, etc.
  3. Public event hooks, exception types, and configuration model abstractions.
  4. Addon self-registration interfaces via RTPServerAccessor.
  5. Platform-Neutral SPI Modules:
  6. commands-api (io.github.dailystruggle.commandsapi.common.*): Command tree abstractions, parameter parsers, command contexts.
  7. effects-api (io.github.dailystruggle.effectsapi.common.*): Platform-neutral visual/auditory effect models.
  8. maps-api (io.github.dailystruggle.mapsapi.common.*): Minimap/chart rendering models and specs.
  9. metrics-api (io.github.dailystruggle.metricsapi.common.*): Telemetry SPI interfaces.
  10. anvil-api (io.github.dailystruggle.anvilapi.*): Platform-neutral Anvil chunk and region file decoders, and the RegionFileReader SPI for addon-supplied region formats.
  11. tags-api (io.github.dailystruggle.tagsapi.*): Block and biome tag query interfaces.
  12. yaml-api (io.github.dailystruggle.rtp.common.configuration.yaml.*): Hand-rolled zero-dependency YAML parser AST types (RtpYaml*).

Public API Guarantees: - Binary and source compatibility preserved across MINOR and PATCH releases. - Deprecation cycle: At least two minor versions (or one major release) notice with @Deprecated(forRemoval = true, since = "...") before removal (per DEPRECATION_POLICY.md). - No unannounced signature alterations, return-type modifications, or thrown checked-exception additions.

2.2 Internal Implementation (Non-Public, No SemVer Guarantees)

Classes and packages outside the designated public API surface are internal implementation details:

  1. rtp-core (io.github.dailystruggle.rtp.common.*):
  2. Core runtime algorithms: selection pipeline (TeleportPipelineTask), spiral coordinate math, caching engines (RegionQueueManager), memory trackers (MemoryTracker), and database accessors.
  3. Internal utility classes, internal config parser implementations, and concurrency machinery.
  4. Note for Addons: While advanced addons may inspect core classes, these classes do not carry SemVer stability guarantees and may be refactored across minor versions.
  5. Platform Adapters & Shims:
  6. rtp-bukkit, rtp-paper, rtp-folia, rtp-fabric, rtp-neoforge.
  7. Per-version NMS/intermediary carrier shims (rtp-*-vXX_YY_R1).
  8. Platform-specific scheduling, reflection, and event listeners.
  9. Assembly & Entry Points:
  10. rtp-plugin bootstrap, jar shading, and command forwarding classes.
  11. rtp-proxy-velocity internal channel messaging handlers.

3. Deprecation and Evolution Rules

  • Deprecations in the public API must be documented in CHANGELOG.md under ### Deprecated.
  • Removal of public API elements occurs only upon a MAJOR version boundary.
  • If an urgent security or platform-safety fix requires altering an API contract in a minor release, it must be documented prominently in the release notes with an emergency compatibility shim or migration guide provided.