Skip to content

Commit a641987

Browse files
ctruedenclaude
andcommitted
Migrate incarnational versioning writeup to here
Before now, it resided in the README of the SciJava incubator project. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 680d702 commit a641987

10 files changed

Lines changed: 148 additions & 9 deletions

File tree

‎cli/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
<artifactId>scijava-cli</artifactId>
1313
<!--
14-
NB: the major version tracks the incarnation, per the incubator README.
14+
NB: the major version tracks the incarnation; see docs/versioning.md.
1515
The 1.x.y of the other components is a legacy of the first monoversioned
1616
release, not the intended scheme.
1717
-->

‎compat/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
<artifactId>scijava-compat</artifactId>
1313
<!--
14-
NB: the major version tracks the incarnation, per the incubator README.
14+
NB: the major version tracks the incarnation; see docs/versioning.md.
1515
The 1.x.y of the other components is a legacy of the first monoversioned
1616
release, not the intended scheme.
1717
-->

‎convert3/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
<artifactId>scijava-convert3</artifactId>
1313
<!--
14-
NB: the major version tracks the incarnation, per the incubator README.
14+
NB: the major version tracks the incarnation; see docs/versioning.md.
1515
The 1.x.y of the other components is a legacy of the first monoversioned
1616
release, not the intended scheme.
1717
-->

‎docs/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@
6868
"examples/README.md",
6969
"migration.md",
7070
"migration-plan.md",
71+
"versioning.md",
7172
]
7273

7374
# -- MyST-Parser/MyST-NB configuration ---------------------------------------

‎docs/migration-plan.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,7 @@ The deliverable is not a reimplementation of SJC. It is:
4646
workaround for a package collision; it is the component's *incarnation*.
4747
Breaking changes are made by forking to a new incarnation with a new
4848
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).
49+
and downstream code keeps working. See [versioning.md](versioning.md).
5150
- **A major version bump within one incarnation should never happen.** If
5251
compatibility must break, bump the incarnation digit — artifactId, package
5352
prefix and major version together — so the old one can stay loaded

‎docs/versioning.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Versioning and compatibility
2+
3+
How components in this repository are named, versioned and evolved, and why.
4+
These principles were first worked out in the
5+
[SciJava incubator](#history-the-scijava-incubator), which this repository
6+
replaced; this document keeps the parts that still govern development here.
7+
8+
Companion document: [migration-plan.md](migration-plan.md), which applies
9+
these rules to the migration of SciJava Common.
10+
11+
## The requirement: scripts keep working
12+
13+
ImageJ and Fiji are not software products so much as living processes, and
14+
their users expect a script written against the public API to keep working
15+
for many years. At the same time, some bugs cannot be fixed, and some designs
16+
cannot be improved, without changing that API. The goal is to have both:
17+
downstream code keeps working, *and* the codebase can still improve.
18+
19+
SemVer alone does not achieve this. A major version bump announces a break,
20+
but it does not prevent one: a downstream component built against `2.x` fails
21+
as soon as anything else on the classpath pulls in `3.x`, because only one
22+
version of a given artifact can be loaded. Every component in the stack is
23+
then forced to migrate in lockstep.
24+
25+
## Incarnational versioning
26+
27+
When a component needs a change that cannot be made compatibly, it is not
28+
given a new major version. It is forked to a new **incarnation**: a new
29+
artifactId *and* a new package prefix, both carrying the incarnation number.
30+
For example, `scijava-common3` lives in `org.scijava.common3`, and a future
31+
incompatible successor would be `scijava-common4` in `org.scijava.common4`.
32+
33+
Because the two incarnations share no artifact and no package, both can be on
34+
one classpath at once. Code written against the old incarnation keeps running
35+
unchanged, while new code adopts the new one, and each downstream component
36+
migrates on its own schedule rather than all at once.
37+
38+
The rules:
39+
40+
- **Never bump the major version within an incarnation.** If compatibility
41+
must break, bump the incarnation digit instead: artifactId, package prefix
42+
and major version together.
43+
- **The major version equals the incarnation number**, so that
44+
`scijava-io3` is at `3.x.y`, to avoid confusion about which number means
45+
what. (The `1.x.y` of most components here is a legacy of the first
46+
monoversioned `1.0.0` release, not the intended scheme; see
47+
[migration-plan.md](migration-plan.md) for how it is being realigned.)
48+
- **Deprecate before you fork.** Within an incarnation, API is retired by
49+
deprecation, which keeps scripts working while pointing at the replacement.
50+
A new incarnation is for changes that deprecation cannot express.
51+
- **The number is the incarnation, not a collision workaround.** Where a new
52+
package would collide with an existing one and no incarnation applies, pick
53+
a natural, collision-free noun instead of inventing a digit. Every such
54+
decision is recorded in [migration.md](migration.md).
55+
- **Incarnations do not share data structures.** An object from `common3` is
56+
not inherently usable where `common4` expects its counterpart. Bridging the
57+
two is the job of an explicit compatibility layer, written when a concrete
58+
need appears; apart from such layers, a component uses one incarnation of
59+
each dependency at a time.
60+
- **Fixes do not automatically cross incarnations.** Whether a fix is ported
61+
forward or back is decided case by case. Keeping the period during which two
62+
incarnations are both actively developed short keeps that cost small.
63+
64+
### Only the system class loader
65+
66+
An earlier approach
67+
([forum post](https://forum.image.sc/t/8393)) isolated incompatible versions
68+
with custom class loaders. That turned out to limit deployment: tools that
69+
embed the JVM, such as Python bridges, might only be able to wrap classes from
70+
the system class loader. Incarnations need nothing but distinct names, so they
71+
work on a plain classpath, with no class loader tricks, for arbitrarily long.
72+
73+
### Transitive dependencies do not cascade
74+
75+
Suppose `imagej-common3` depends on `scijava-magic5`, and later moves to
76+
`scijava-magic6`. Must `imagej-common3` itself become a new incarnation? Not as
77+
long as no `scijava-magic5` type appears in its public API. A downstream tool
78+
that uses both `scijava-magic5` and `imagej-common3` will simply end up with
79+
both `scijava-magic5` and `scijava-magic6` on its classpath, and that is fine,
80+
since they share nothing.
81+
82+
This is what prevents a domino effect, where one incarnation bump forces bumps
83+
in everything above it. It is also a strong reason to keep dependency types
84+
out of public API.
85+
86+
### Deprecated clutter
87+
88+
Over time an incarnation accumulates deprecated classes. Moving them into a
89+
separate `-deprecated` component is not an option, because the packages would
90+
be split across two modules, which JPMS forbids. When the clutter becomes a
91+
real problem, that is a sign the next incarnation is due.
92+
93+
## Minimal API surface
94+
95+
The smaller the public API, the less there is that can never change. So:
96+
97+
- As few public classes and methods as possible, and interfaces wherever
98+
possible.
99+
- Every component is a JPMS module that exports only its API packages.
100+
Implementation packages stay unexported.
101+
- No code in a blanket package prefix such as the root `org.scijava` package.
102+
Each component owns its own package prefix, which keeps packages from being
103+
split across modules.
104+
105+
## Release early, but stable
106+
107+
The traditional mantra is "release early, release often". Its failure mode is
108+
that a half-finished design gets released, gets adopted, and is then frozen by
109+
the compatibility promise above. The refinement: release as early as possible,
110+
but make that release one you are prepared to support indefinitely. Before
111+
then, restructure freely; afterward, change compatibly or fork an incarnation.
112+
113+
## Monoversioning per layer
114+
115+
The core components of each layer of the stack live together in one
116+
multi-module repository: this one, for SciJava. That gives one place to find
117+
code and file issues, keeps tightly coupled modules building against each
118+
other in CI, and makes it obvious which versions go together. Add-ons that
119+
merely build on the core stay in their own repositories.
120+
121+
The first release from this repository was a single monoversioned `1.0.0`,
122+
because releasing a reactor whose modules have different versions needs
123+
release tooling that did not yet exist. The intent is for each component to
124+
carry its own version, with the major version following its incarnation, as
125+
described above.
126+
127+
## History: the SciJava incubator
128+
129+
From 2020 until 2024, new core development happened in the
130+
[SciJava incubator](https://github.com/scijava/incubator), a single
131+
repository where immature components could be restructured freely at version
132+
`0-SNAPSHOT`, breaking changes were caught across all of them by one CI build,
133+
and each component graduated once ready for `1.0.0`. The incubator was where
134+
SciJava Ops and the other components here took shape, and it is where the
135+
principles above were first written down.
136+
137+
With everything graduated into this repository, the incubator is retired and
138+
archived. Its one component that never graduated, `scijava-persist`, is
139+
discussed in [migration-plan.md](migration-plan.md).

‎io3/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
<artifactId>scijava-io3</artifactId>
1313
<!--
14-
NB: the major version tracks the incarnation, per the incubator README.
14+
NB: the major version tracks the incarnation; see docs/versioning.md.
1515
The 1.x.y of the other components is a legacy of the first monoversioned
1616
release, not the intended scheme.
1717
-->

‎ops-indexer/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ To enable Op YAML generation in your build process, add the following to your `p
1212
</properties>
1313
```
1414

15-
**NOTE**: Until this repository is moved out of the SciJava Incubator and the following is added to pom-scijava, the following must also be added to your POM:
15+
**NOTE**: Until the following is added to pom-scijava, the following must also be added to your POM:
1616

1717
```xml
1818
<build>

‎script3/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
<artifactId>scijava-script3</artifactId>
1313
<!--
14-
NB: the major version tracks the incarnation, per the incubator README.
14+
NB: the major version tracks the incarnation; see docs/versioning.md.
1515
The 1.x.y of the other components is a legacy of the first monoversioned
1616
release, not the intended scheme.
1717
-->

‎settings/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
<artifactId>scijava-settings</artifactId>
1313
<!--
14-
NB: the major version tracks the incarnation, per the incubator README.
14+
NB: the major version tracks the incarnation; see docs/versioning.md.
1515
The 1.x.y of the other components is a legacy of the first monoversioned
1616
release, not the intended scheme.
1717
-->

0 commit comments

Comments
 (0)