ADR-126 - Multi-Product Monorepo Release Architecture (RTP: Real-Time Process / Program for Minecraft)¶
Status: Accepted Date: 2026-10-27 Extends: ADR-108, leafrtp-ADR-087
Context¶
The DailyStruggle/RTP repository has evolved from a single plugin into the Real-Time Process / Real-Time Program (RTP) for Minecraft ecosystem, backed by the private LeafCraftDev/MC (main branch) monorepo trunk: an umbrella workspace hosting 17 platform-neutral real-time SDK modules (api/*, rtp-api, rtp-core, rtp-proxy-common), multiple standalone multi-loader resources (resource/LeafRTP, resource/LeafTreeGen, resource/LeafSleep, resource/LeafSleuth, resource/LeafConfig, resource/LeafArtifacts, resource/LeafShapeMining), standalone and bundled addons (addons/*), and verification harnesses (helpers/*).
Retaining the DailyStruggle/RTP repository coordinate (V1, V2, V3) while framing RTP as Real-Time Process / Real-Time Program preserves every existing Git remote, documentation link, Maven Central SCM URL, and JitPack coordinate (com.github.DailyStruggle.RTP:<module>:<tag>). However, GitHub's native release model is repository-scoped:
- Flat tag namespace: Git tags live in a single repository-wide namespace (
refs/tags/*), and every GitHub Release is bound 1-to-1 to a Git tag. Two products in the same repository cannot both tagv1.0.0. - Single
Latestpointer: GitHub maintains only oneLatestrelease badge and/releases/latestredirect per repository. If a sibling plugin workflow publishes a release withmake_latest: true(the GitHub API andsoftprops/action-gh-releasedefault),/releases/latestonDailyStruggle/RTPpoints to that sibling plugin instead ofLeafRTP. - Downstream polling ambiguity: Release consumers that query
/repos/DailyStruggle/RTP/releases(such asdiscord-support-bot) must distinguish betweenLeafRTPreleases (v3.3.1/leafrtp-v3.3.1) and sibling product releases (leaftreegen-v0.2.0,leafsleep-v1.0.0). - Independent lifecycles: Multi-loader resources under
resource/*have their own semantic version lines and changelogs (resource/LeafTreeGen/CHANGELOG.md), and releasing a sibling resource must not require bumpingLeafRTPor triggering Maven Central SDK publication.
Decision¶
- Umbrella Repository Identity (
RTP= Real-Time Process / Program) &resource/Layout: -
All multi-loader plugins and mods in the monorepo reside under
resource/<Product>/(resource/LeafRTP,resource/LeafTreeGen,resource/LeafSleuth,resource/LeafConfig,resource/LeafArtifacts,resource/LeafShapeMining,resource/LeafSleep). -
Component-Prefixed Git Tags (
<product>-v<semver>): - Nested plugins, addons, and tools published from the monorepo shall use hyphen-delimited component-prefixed Git tags of the form
<product>-v<semver>(for example,leaftreegen-v0.2.0,leafsleuth-v0.1.0,leafconfig-v0.1.0,leafsleep-v1.0.0,stresstest-v1.0.0) and product-titled GitHub Releases (LeafTreeGen 0.2.0,LeafSleuth 0.1.0,LeafConfig 0.1.0,LeafSleep 1.0.0). - Hyphens (
<product>-v<semver>) shall be used instead of slashes (<product>/v<semver>) so tag refs remain flat under.git/refs/tags/, URL-safe across HTTP routers, and compatible with JitPack and artifact filename conventions. -
LeafRTP(leafrtp) retains barev<semver>tags (e.g.v3.3.1) as its primary tag format for backward compatibility with existing JitPack consumers and leafrtp-ADR-087, while release discovery tooling accepts bothv<semver>andleafrtp-v<semver>. -
Explicit
make_latestInvariant on GitHub Releases: - Only the flagship
LeafRTPrelease workflow (.github/workflows/release.yml) shall setmake_latest: true(for non-prerelease versions) sohttps://github.com/DailyStruggle/RTP/releases/latestdeterministically resolves toLeafRTP. -
All nested plugin, addon, and helper release workflows (
.github/workflows/release-sleep.yml,.github/workflows/release-treegen.yml,.github/workflows/release-anvil.yml,.github/workflows/release-fuzz.yml,.github/workflows/release-sleuth.yml,.github/workflows/release-config.yml) shall explicitly setmake_latest: falseonsoftprops/action-gh-release. -
Per-Product Version, Changelog, Workflow Isolation, and Option A Bidirectional OSS Sync:
- Each multi-loader resource lives under
resource/<Product>/(../../resource/LeafRTPforLeafRTPmodulesrtp-api,rtp-core,rtp-plugin, andaddons;resource/LeafSleep/forLeafSleep/OnePlayerSleep;resource/LeafTreeGen/forLeafTreeGen;resource/LeafAnvil/forLeafAnvil&LeafAnvil-Net;resource/LeafFuzz/forLeafFuzz, etc.). In the privateLeafCraftDev/MCmonorepo (mcremote, branchmain), all resources build and navigate in a single workspace. scripts/release/sync_public_oss_pr.py(enforced by.git/hooks/pre-pushandscripts/pre_push_guard.py) projects Option A per-resource public OSS repositories (--target rtp->DailyStruggle/RTP:V3;--target sleep->LeafCraftDev/LeafSleep:main;--target treegen->LeafCraftDev/LeafTreeGen:main;--target fuzz->LeafCraftDev/LeafFuzz:main) that share overarchingdocs/(docs/dev/*,docs/adr/ADR-*.md) while exporting only that target'sresource/<Product>/**tree (including its<product>-ADR-*.mdandREQUIREMENTS.md). By default (--sdk-mode maven), the sharedapi/*SDK modules are published as Maven artifacts (io.github.dailystruggle:<module>:<version>, with-sources.jar,-javadoc.jar, andMETA-INF/leaf-sdk/<module>/docs) fromLeafCraftDev/MC(main), consumed/shaded/resupplied via Maven coordinates in the projected repositories, and their Markdown guides (api/**/*.md) are projected todocs/sdk/alongside a generateddocs/sdk/BUNDLED_SDK.mdcatalog (--import-prmapsdocs/sdk/edits and Gradle coordinates back toapi/andproject(':<module>')inLeafCraftDev/MC).- Sibling resources under
resource/<Product>/own their version in their leafbuild.gradle(e.g.resource/LeafTreeGen/treegen-plugin/build.gradle) and their release notes inresource/<Product>/CHANGELOG.md, whileLeafRTP(../../resource/LeafRTP) keeps its flat Gradle coordinates (:rtp-api,:rtp-core,:rtp-plugin,:addons:*) viaprojectDirmappings insettings.gradle. - Each nested resource has a dedicated release workflow (
.github/workflows/release-<product>.yml, alongside.github/workflows/release.ymlandrelease-bbb.ymlforLeafRTP) triggered by pushing a matching<product>-v*.*.*tag or viaworkflow_dispatch. -
Every product release workflow in the monorepo enforces the same supply-chain guarantees as
LeafRTP: in-memory PGP.ascsigning (SIGNING_KEY),.sha256and.sha512checksums, and GitHub SLSA build provenance (actions/attest-build-provenance). -
Tag-Prefix Release Discovery in
discord-support-bot: projects.<project>.releaseindiscord-support-bot/support-bot.ymlandPluginReleaseAndStatusManager.fetch_latest_release()support an optionalgithub_tag_prefixfilter (a prefix string or list of prefix strings, matched with a version digit guard right after the prefix).- When
github_tag_prefixis configured,fetch_latest_release()verifies/releases/latestagainst the allowed prefix(es) and falls back to scanning/repos/{gh_repo}/releases?per_page=30for the newest release whosetag_namematches the product's prefix and strips that prefix to extract the clean version string.
Alternatives Considered¶
| Alternative | Why Rejected |
|---|---|
| Separate source repositories per plugin | Duplicates the 17-module api/* SDK, Gradle conventions, CI gates, and signing secrets across repositories; forces cross-repo version bumps for shared SPI changes. |
Slash-separated tags (leaftreegen/v0.2.0) |
Creates nested directories under .git/refs/tags/, breaks URL path segments that expect a single token, and complicates shell/artifact filename handling. |
Leaving make_latest at default (true) on all workflows |
Whichever plugin was released most recently would overwrite /releases/latest for the entire DailyStruggle/RTP repository. |
Automated commit-bot release PRs (release-please / changesets) |
Conflicts with curated Keep-a-Changelog authoring and ADR-117 contractual Pro vs. discretionary Lite cadence. |
Consequences¶
- Positive:
- Multiple plugins (
leafrtp,leaftreegen,leafsleep, etc.) ship distinct, signed, provenance-attested releases from one repository using a single set of repository secrets (SIGNING_KEY,MODRINTH_TOKEN,HANGAR_TOKEN,DISCORD_BOT_TOKEN). /releases/latestonDailyStruggle/RTPnever drifts away fromLeafRTP.discord-support-botresolves per-plugin releases accurately whether a plugin publishes toDailyStruggle/RTP(viagithub_tag_prefix) or to a dedicated mirror repository.- Existing JitPack coordinates and
ADR-117workflows continue to work without breaking changes. - Negative / Trade-offs:
- The chronological
/releasesfeed onDailyStruggle/RTPlists releases across all monorepo products, distinguished by release title (rtp-lite 3.3.1,LeafTreeGen 0.2.0) and tag prefix (v3.3.1,leaftreegen-v0.2.0).
References¶
.github/workflows/release.yml,.github/workflows/release-bbb.yml,.github/workflows/release-treegen.yml.resource/LeafTreeGen/treegen-plugin/build.gradle,resource/LeafTreeGen/CHANGELOG.md.discord-support-bot/discord_support_bot.py,discord-support-bot/support-bot.yml.docs/dev/PUBLISHING.md.- ADR-108, leafrtp-ADR-087.