[ImageJ-devel] SemVer policies for ImageJ2 and Fiji

[Stephan Saalfeld]

Hi Mark and everybody,

I am concerned about the PATCH counter and the notion of `unintended'
behavior (what's that in the first place).  A strict definition of the
public API would classify a bug-fix that changes the output of a method
from wrong to correct as a break, i.e. MAJOR upgrade.  If we would
follow this scheme, MINOR and PATCH increments are safe to consume, i.e.
do not change behavior.  If we, however, say that patches of
`unintended' behavior (bugfixes) lead to a PATCH counter increase, MAJOR
and PATCH increases are technically equivalent, and thanks to the SemVer
policy to roll PATCH on MINOR (1.1.5 > 1.2.0), MINOR does not exclude
PATCH, i.e. MAJOR == MINOR == PATCH == unsafe.  I certainly understand
that treating bugfixes as API-breakage is even farther from `romantic
versioning' than our current understanding of SemVer, but it seems the
only way to get at least something out of those numbers.

Please let me know what you think.

Best,
Stephan



On Mon, 2015-03-16 at 13:18 -0500, Mark Hiner wrote:
> 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
> > >
> > >
> > >
> >
> >