[ImageJ-devel] SemVer policies for ImageJ2 and Fiji

[Mark Hiner]

Hi Stephan,

>`unintended' behavior (what's that in the first place)

For example, if I have class Foo with method add(int, int) that behaves as
one might expect, except for the following edge case: Foo.add(0, -1) = 256.
That is unintended behavior. If I fix my implementation so that Foo.add(0,
-1) = -1 I have changed behavior but not the traditional definition of
public API[1,2]. Thus this change is within the scope of the PATCH version
of SemVer.

>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.

> and thanks to the SemVer policy to roll PATCH on MINOR (1.1.5 > 1.2.0)

Just to make sure we're on the same page - when you say "changes the
output", I assume you mean "changes the behavior but not the API - i.e.
return type is unchanged" because SemVer already requires bug fixes that
change API to be MAJOR version bumps.

In that case, I think it would be cleaner to just eliminate the PATCH
number - because every bug fix necessarily changes behavior, right? So with
this scheme, MAJOR increases = "existing behavior has changed", and MINOR
increases = "new behavior is available".

Some problems with creating this versioning scheme:
1. MAJOR versions will increase rapidly. This is aesthetic, but one that
people can react very negatively to - and can certainly be confusing if
people don't expect MAJOR version bumps to cover bug fixes.
2. It's one more thing for external developers to learn. We can't just say
"we use SemVer".
3. Since this is an internal versioning scheme, it may not be easy to
compare our versions with external project versions that use SemVer.
4. There will be false negatives for MAJOR version compatibility
comparisons (instead of what could be considered false positives with
SemVer)

Unfortunately, #1 above alone makes it very unlikely that we would want to
adopt this use of version numbers. But what you're trying to do here -
ensure compatibility - is fantastic and something that would be great to
have.

So let's take a step back and look at what guarantees we do and do not have
right now:

+ We have reproducible builds (release couplings, which requires -some-
versioning scheme to be used)
+ We have API compatibility (SemVer)

- We do not have strict behavior compatibility
- We do not have dependency compatibility

Behavior and dependency compatibility are very closely related - if they
were covered by a versioning scheme, we could automatically answer the
question "is it safe to drop in version X to replace version Y?".

However, I do not think we should conflate these concerns with SemVer.
Instead, two potential options would be:

1) Continue to use SemVer, accept its limitations, be content with
reproducibility.
2) Create a separate versioning scheme that covers behavior and dependency
compatibility. Use it in tandem with SemVer.

If anyone can think of other examples of versioned guarantees that would be
useful to have, or counter-examples to any claims made here - please share!

Also, please let me know if any of this is confusing and/or additional
examples would be useful.

Thanks again for the continued discussion,
Mark

[1]
http://en.wikipedia.org/wiki/Application_programming_interface#API_in_object-oriented_languages
[2]
http://stackoverflow.com/questions/2954372/difference-between-spi-and-api
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://imagej.net/pipermail/imagej-devel/attachments/20150327/ce507ca1/attachment-0001.html>