diff --git a/docs/API.md b/docs/API.md index 9fed31b..f628f7f 100644 --- a/docs/API.md +++ b/docs/API.md @@ -17,7 +17,8 @@ FMP still needs Scala at runtime, and generated-trait behavior remains covered s **Rebuilding an existing mod against this branch? Read the [release notes](RELEASE_NOTES.md) first.** Shipped binaries keep working, but recompiling has three classes of break, and the trait-composition one compiles cleanly and changes -behavior at runtime. +behavior at runtime. Use the [consumer migration checklist](api/MIGRATION_CHECKLIST.md) to carry a source change through +runtime validation, release and target-pack adoption. ## Direct calls and optional integration diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md index 10989c3..ff72195 100644 --- a/docs/RELEASE_NOTES.md +++ b/docs/RELEASE_NOTES.md @@ -7,7 +7,8 @@ descriptor and reflective name the audited consumers use was preserved deliberat still link. The compatibility ledger for what did change is [JAVA_MIGRATION_DIVERGENCES.md](../JAVA_MIGRATION_DIVERGENCES.md). **If you rebuild against the new dev jar, read on.** Recompiling is the case that breaks, and one class of break is -silent. There are three kinds, in descending order of how badly they fail. +silent. There are three kinds, in descending order of how badly they fail. The [consumer migration checklist](api/MIGRATION_CHECKLIST.md) +turns the cases below into concrete compile, runtime, release and pack-adoption gates. ## 1. Linkage errors: the generated tile traits diff --git a/docs/api/MIGRATION_CHECKLIST.md b/docs/api/MIGRATION_CHECKLIST.md new file mode 100644 index 0000000..68c6350 --- /dev/null +++ b/docs/api/MIGRATION_CHECKLIST.md @@ -0,0 +1,58 @@ +# Consumer migration checklist + +[API index](../API.md) ยท [Java-port release notes](../RELEASE_NOTES.md) + +Use this when rebuilding a mod against the Java-port artifact. It is a release checklist, not a replacement for the +method-specific guides linked from the API index. + +## Before editing + +- [ ] Inventory source and reflective references to `codechicken.multipart` and `codechicken.microblock`, including + inherited traits, companion objects, `$class` helpers and private fields. +- [ ] Preserve published part/material IDs, NBT keys and packet field order unless the change includes an explicit data + migration or protocol break. +- [ ] Identify the exact FMP artifact used to compile and run. New Java APIs on `algent/java` have no minimum published + version yet; require a release that actually contains every method used. +- [ ] If FMP is optional, keep FMP-typed code in a compatibility class loaded only after checking mod presence and a + supported version. Keep FMP types out of classes loaded unconditionally. + +## Change the integration + +- [ ] Prefer the documented direct API over companion lookup, private-field access or new reflection. +- [ ] Call generated tile behavior through `TileMultipart` or a stable capability interface such as `IRedstoneTile`, + `IInventory`, `ISidedInventory` or `IFluidHandler`. Do not compile method or field access against raw classes under + `codechicken.multipart.scalatraits` or `TileMultipartClient`; Forge transforms those classes into interfaces. +- [ ] For recompiled Scala traits, audit every method formerly supplied by trait linearization. A successful compile is + insufficient: Java superclass methods can silently win over interface defaults. Apply the explicit forwarders in + the [release notes](../RELEASE_NOTES.md#2-silent-behavior-changes-recompiled-scala-trait-composition). +- [ ] Use `canPlacePart` followed by `addPart` for normal server placement, and `remPart` for removal. Retain the tile + returned by additions/removals because generated capabilities can replace the container; final removal returns null. +- [ ] Use `save`/`load` for server persistence and `writeDesc`/`readDesc` or a symmetric custom update for clients. + Mark persistent state dirty, synchronize client-visible state and notify parts/neighbors only when that state needs + each effect. See the [custom-part lifecycle](CUSTOM_PARTS.md). +- [ ] Treat `generateCompositeTile`, `setPartList` and `loadPartList` as reconstruction operations. Follow their state, + binding, installation and notification responsibilities instead of substituting them for ordinary placement. + +## Verify the rebuilt consumer + +- [ ] Compile against the same FMP artifact required at runtime, then inspect the rebuilt bytecode for references to raw + transformed trait classes, removed Scala-shaped entry points and legacy private fields. +- [ ] Test optional integration with FMP absent and present. Test a dedicated server separately from a physical client; + headless Forge coverage does not establish client class stripping, rendering or GPU behavior. +- [ ] Load representative pre-migration saves and exercise placement, updates, removal, chunk reload and movement for + every changed part or integration. Verify NBT and packet state, generated capabilities and callback order. +- [ ] Run the rebuilt jar in the target pack with the actual interacting mods. Record manual limits instead of treating + source inspection or isolated tests as full-pack proof. + +## Close adoption before removing compatibility + +A source patch proves only that the migration was written. Keep the old bridge, descriptor, field or Scala runtime +path until all applicable gates are complete: + +1. The consumer patch is merged and its rebuilt jar passes the checks above. +2. A consumer release containing that jar exists. +3. The target pack requires the compatible FMP and consumer releases. +4. A fresh consumer scan confirms no supported released jar still uses the legacy contract. + +Documented Java entry points are intended to survive later Scala removal. Undocumented public members, raw transformed +classes and Scala-shaped bridges do not gain that guarantee merely because current source can call them.