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.
This commit is contained in:
Algent committed 2026-09-09 16:46:23 +02:00
1 parent 94633dee92
commit 92a1f82427
1 file changed
+27
+27
View File
@@ -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.