|
| 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). |
0 commit comments