docs: add consumer migration checklist

This commit is contained in:
Algent committed 2026-09-14 12:04:03 +02:00
1 parent bf4343d1fc
commit 1de11db82d
3 files changed
+62 -2

No files matched your search

+2 -1
View File
@@ -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
+2 -1
View File
@@ -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
+58
View File
@@ -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.