[ImageJ-devel] SemVer policies for ImageJ2 and Fiji

[Mark Hiner]

Hi Stephan,

Thanks for starting this thread!

For those interested, there was further discussion in IRC
<http://code.imagej.net/chatlogs/imagejdev?times=prefix&start-date=2015-03-16&end-date=2015-03-16#20150316T155138>
today, and Curtis and I chatted briefly face-to-face.

Basically, we agree that semver must be limited in scope to the public API
of a given project. Checking for dependency convergence must be handled
separately. Bubbling versions through dependencies is not significantly
meaningful.

Documentation on this (and other versioning issues) is on the wiki:
http://imagej.net/Architecture#Versioning

>Artifact Y depends on artifact X and knew about the bug and had a
workaround in place to compensate for it

As a side note, semver does not guarantee preservation of unintentional
behavior. As long as behavior is fixed in a way that's backwards-compatible
with public API, only patch versions need to change.

However, the idea is that a BOM will account for such a change, to avoid
dependency skew.

Best,
Mark


On Sun, Mar 15, 2015 at 9:38 PM, Stephan Saalfeld <
saalfelds at janelia.hhmi.org> wrote:

> Dear ImageJ developers,
>
> my earlier statement about the conclusion that can be drawn from
> bubbling versions in a deployment context are wrong.
>
> Counter proof: Artifact X fixes a bug in one of its public methods, and
> accordingly increases the PATCH counter.  Artifact Y depends on artifact
> X and knew about the bug and had a workaround in place to compensate for
> it.  On upgrade of dependency version for X, it removes the workaround,
> public API remains unchanged.  This is a patch and X had increased the
> PATCH counter, so Y increases the PATCH counter.  Neither X nor Y can be
> deployed independently.  The deployment system (or person) has to
> inspect the entire dependency tree to calculate a correct state or a
> conflict.  The same is true in the non-bubbling situation.  Ergo,
> bubbling versioning has no advantage over non-bubbling versioning in a
> deployment context.
>
> This leads me to the conclusion that non-bubbling versioning is better
> because it carries local information for developers that non-bubbling
> versioning does not, i.e. in what way the API of the versioned artifact
> was changed.
>
> I expect to be wrong still and that I missed something important.
>
> Looking forward to your responses.
>
> Thanks,
> Stephan
>
>
>
> On Sat, 2015-03-14 at 23:12 -0400, Stephan Saalfeld wrote:
> > Dear list,
> >
> > a recent SPIM_Registration bug report on GitHub
> >
> >
> https://github.com/bigdataviewer/SPIM_Registration/issues/10#issuecomment-79721014
> >
> > resulted in a discussion about the correct way of assigning version
> > numbers to individual artifacts.
> >
> > We have earlier settled to follow SemVer
> >
> > http://semver.org/
> >
> > which has reasonably clear guidelines under what circumstances to
> > increase which of three version counters.
> >
> > <quote src="http://semver.org/">
> > 1. MAJOR version when you make incompatible API changes,
> > 2. MINOR version when you add functionality in a backwards-compatible
> > manner, and
> > 3. PATCH version when you make backwards-compatible bug fixes.
> > </quote>
> >
> > It is unspecified, however, how version changes in dependency artifacts
> > affect the version of the consuming artifact, i.e. do they bubble or do
> > they not?  In my current understanding, there are two competing
> > objectives, deployment (advocated and executed by @dscho and @ctrueden),
> > and development (advocated and executed by @axtimwalde and @ctrueden, we
> > see that @ctrueden is ambivalent, @axtimwalde too, as always, just that
> > you know):
> >
> > 1.
> > Developer perspective: Don't bubble!  Developers that use the public API
> > of an artifact X in their code use SemVer to reason whether on upgrade
> > of X they will have to change their code or simply recompile with no
> > modification.  Dependency version bubbling would break this contract,
> > because it signalizes API incompatibility in X when a dependency Y of X
> > introduces incompatible changes, although this incompatibility does not
> > affect the public API of X.  Deployment of a set of artifacts following
> > this contract requires complete inspection of the entire set of
> > artifacts to guarantee consistency of the deployed version by other
> > means (maven pom tracing?) because the SemVer versions of individual
> > artifacts do not encode the necessary information.  I have the
> > impression that the developer perspective, ignoring it not being helpful
> > for deployment, was the driver of the SemVer specification and have a
> > preference for it because...
> >
> > 2.
> > Deployer perspective: Bubble?  Deployers could use SemVer to reason
> > whether a new version of an artifact has ANY incompatible changes
> > anywhere in its dependency tree.  This is useful to know when an
> > artifact in the tree can be released *without* considering its
> > dependents *and* dependencies (PATCH increase).  However, whenever the
> > version number signalizes incompatibility (MAJOR) or new features
> > (MINOR), further inspection of the entire dependency tree is required
> > because consistency cannot be derived from SemVer versions alone.  The
> > only definite conclusion that can be made from observing that an
> > artifact changes its MAJOR or MINOR version, i.e. becomes incompatible,
> > is that all dependents will need to be updated/ recompiled or that
> > there's a problem, consistency across artifacts cannot be guaranteed.
> > I.e. the bubbling scheme, at every individual artifact, sends a signal
> > when further inspection is required.  This information, however is
> > binary, and a single counter would suffice to do that.  If patch
> > counters are desired, one would need two.  The MAJOR and MINOR counters
> > are redundant.
> >
> > Short:
> > Non-bubbling SemVer tells a developer whether her code will compile with
> > a given dependency artifact (PATCH and MINOR).  Bubbling SemVer tells a
> > deployer when a single artifact can be deployed without considering its
> > environment (PATCH).  Both things exclude each other.  In this setup, I
> > find the benefit for developers stronger and therefore prefer
> > non-bubbling SemVer.
> >
> > An interesting animal are dependency management poms (BOMs) such as
> > pom-fiji or pom-mpicbg.  Their `public API' is the composite of  managed
> > dependencies and therefore it has to bubble the SemVer versions of the
> > managed dependencies.  This is different from artifacts that consume a
> > dependency, consuming and managing are different.  I may be wrong, but I
> > have the impression that these two things often get confused.
> >
> > Please let me know your thoughts.
> >
> > Thanks,
> > Stephan
> >
> >
> >
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://imagej.net/pipermail/imagej-devel/attachments/20150316/03c61f3a/attachment.html>