From 92a1f824278fc4a8a9b234ae7e5855ea8a9448f6 Mon Sep 17 00:00:00 2001 From: Algent Date: Wed, 9 Sep 2026 16:46:23 +0200 Subject: [PATCH] docs: answer whether consumers migrate twice The notes told consumers what breaks on rebuild but not whether the migration they are being asked to make is final. Without that, the reasonable reading is that adopting the Java surface now buys a second migration when the Scala runtime is removed later. State the guarantee: the removal release drops the Scala-shaped entry points and keeps their Java siblings, so one migration to the documented surface is the whole cost. Name the one way to pay it twice, which is aiming at a raw dev-jar class such as scalatraits.TRedstoneTile instead of the stable IRedstoneTile capability interface. That is the mistake a failing rebuild invites, and it fails at runtime in between. Record two limits honestly: the guarantee covers the documented and audited surface, which is why removal waits on adoption evidence rather than source patches, and the source-layout move out of src/main/scala changes no class, package or descriptor and so is invisible. --- docs/RELEASE_NOTES.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md index c0115f8..5d5182b 100644 --- a/docs/RELEASE_NOTES.md +++ b/docs/RELEASE_NOTES.md @@ -108,3 +108,30 @@ entry points compile with no Scala on the classpath. Start at the [Java API inde Direct typed calls are the intended end state. Reflection snippets in older guides are legacy interoperability options, not the migration target. For optional integration, isolate FMP-typed code in a compatibility class loaded only after mod-presence and version checks, and test both the absent and present cases. + +## Will I have to migrate again? + +No, if you migrate to the documented Java surface. That is the point of shipping it alongside the old one. + +FMP still retains Scala storage, runtime and compatibility bridges. A later release removes them, and that release +removes the **Scala-shaped** entry points: `partList(): scala.collection.Seq`, `operate(Function1)`, +`registerParts(Seq)`, the `$class` trait helpers and the `MODULE$` companions. The Java siblings that replace them +stay. So: + +| What you depend on | What the Scala-removal release does to it | +| --- | --- | +| The documented Java surface: `jPartList`, `forEachPart`, `registerPartFactory`, `refreshPartSlots`, `IRedstoneTile` | Unaffected. One migration, done. | +| The Scala-shaped entry points | Removed. This is the migration being asked for now. | +| A raw dev-jar class such as `scalatraits.TRedstoneTile` | Wrong target. See below. | + +**The one way to migrate twice is to aim at the wrong type.** If a rebuild fails on `TRedstoneTile` and the fix looks +like "cast to the class the dev jar actually shows", that produces the `IncompatibleClassChangeError` in section 1 and +still has to be redone against `IRedstoneTile` afterwards. Always target the stable capability interface, never the +raw class the dev jar exposes for a transformed trait. + +Two honest limits on that guarantee. It covers the surface that is documented here and in the +[compatibility audit](../JAVA_MIGRATION_COMPATIBILITY.md); a dependency in neither can still be caught out, which is +why removal waits on evidence of adoption in released consumer jars rather than on source patches alone. And FMP's own +source layout will change when Scala goes, since the Java sources currently live under `src/main/scala` for joint +compilation. That moves no class, package, descriptor or reflective name, so it is invisible to consumers; only +source-attachment paths in an IDE change.