Skip to content

Commit 6b1507f

Browse files
ctruedenclaude
andcommitted
docs: record incarnational versioning, and defer scijava-persist
The digit in common3 and io3 is the component's incarnation, not a workaround for a package collision: breaking changes fork to a new incarnation with a new artifactId and package prefix, so both can sit on one classpath and downstream code keeps working. The rule that makes deprecate-don't-break coherent: a major version bump within one incarnation should never happen. If compatibility must break, the incarnation digit moves with it. Ideally the major version equals the incarnation number, which today it does not, because the first release of this reactor was a single monoversioned big bang -- releasing a reactor piecemeal with heterogeneous versions needs tooling that release-version.sh does not yet have. Removing the interfaces that moved to scijava-spi is the realignment opportunity, since it breaks compatibility anyway. scijava-persist is recorded as later-phase: the idea is sound and the discovery half is SciJava-shaped, but the code hard-wires Gson into its SPI, vendors Gson's RuntimeTypeAdapterFactory, and is built on Context. A rewrite would be smaller than a port, and there is no concrete core consumer today. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent f58ccb1 commit 6b1507f

1 file changed

Lines changed: 33 additions & 3 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,26 @@ The deliverable is not a reimplementation of SJC. It is:
4242
major version. There is no two-way bridge.
4343
- **Build bridges on demand.** Adapters between SJC and SJ3 are written when a
4444
concrete need appears, not on a schedule.
45-
- **Names are case by case.** Where an SJ3 package would collide with an SJC
46-
one, pick a natural collision-free noun if one exists; otherwise use a `3`
47-
suffix (`common3`, `io3`). Every decision is recorded in
45+
- **Incarnational versioning.** The `3` in `common3` and `io3` is not a
46+
workaround for a package collision; it is the component's *incarnation*.
47+
Breaking changes are made by forking to a new incarnation with a new
48+
artifactId and package prefix, so both incarnations can sit on one classpath
49+
and downstream code keeps working. See the
50+
[incubator README](https://github.com/scijava/incubator/blob/-/README.md).
51+
- **A major version bump within one incarnation should never happen.** If
52+
compatibility must break, bump the incarnation digit — artifactId, package
53+
prefix and major version together — so the old one can stay loaded
54+
alongside.
55+
- Ideally the major version equals the incarnation number
56+
(`scijava-common3` at `3.x.y`). Today it is at `1.x.y`, because the first
57+
release of this reactor was a single monoversioned `1.0.0` big bang:
58+
releasing a multi-module reactor piecemeal with heterogeneous versions
59+
needs tooling support that `release-version.sh` does not yet have. The
60+
realignment opportunity is the removal of the interfaces that moved to
61+
`scijava-spi`, which breaks compatibility anyway and could land as `3.0.0`.
62+
- **Names are otherwise case by case.** Where an SJ3 package would collide
63+
with an SJC one and no incarnation digit applies, pick a natural
64+
collision-free noun. Every decision is recorded in
4865
[migration.md](migration.md).
4966

5067
## Hard constraints
@@ -617,6 +634,19 @@ subsystems, with no dependency on external `scijava-<foo>` components.
617634
intended to work standalone — Parsington, for instance — keep their
618635
independence and should not carry the `scijava-` prefix.
619636

637+
## Later, not now
638+
639+
- **`scijava-persist`** (in the incubator): polymorphic serialization where
640+
the implementations live in *other people's* repositories, resolved by
641+
discovery — a real and recurring need, and the discovery half is exactly
642+
SciJava-shaped. Worth rebuilding when a consumer appears, but not worth
643+
lifting: it hard-wires Gson into its SPI (`IClassAdapter extends
644+
JsonSerializer`), vendors a copy of Gson's `RuntimeTypeAdapterFactory`, and
645+
is built on `Context` + `@Plugin`. A rewrite would be much smaller, since
646+
Jackson has first-class polymorphic support and only the discovery-driven
647+
subtype registration would be ours. Its author ended up inlining equivalent
648+
logic downstream, and there is no concrete core consumer today.
649+
620650
## Open decisions
621651

622652
- **Names:** the execution-layer module, and `scijava-convert3`.

0 commit comments

Comments
 (0)