Open Stack

Currently we don't provide specific guidance on what should happen
when the only changes in a project are dependency changes and a
release is made.

The releases team has been treating a dependency change as 'feature'
rather than 'bugfix' in semver modelling - so if the last release was
1.2.3, and a requirements sync happens to fix a bug (e.g. a too-low
minimum dependency), then the next release would be 1.3.0.

Reasoning about this can be a little complex to do on the fly, so I'd
like to put together some concrete guidance - which essentially means
being able to provide a heuristic to answer the questions:

'Is this requirements change an API break' or 'is this requirements
change feature work' or 'is this requirements change a bugfix'.

It seems clear to me that all three can be true. For example, consider
if library X exposes library Y as part of its API, and library Y's
dependency changes from
Y>=1
to
Y>=2

then thats happening due to an API break - e.g. Y has removed some old
backwards compatibility cruft - X won't break or need changing, and
its possible than none of X's callers will need to change either. But
some of them might have been using some of the thing that went away in
Y==2, and so will break. So its an API break in X. But why would X do
that, surely its doing its own API break - well no, lets say its
adding a feature that was only added in Y==2, then setting the minimum
to 2 is necessary, and entirely unrelated to the fact that an API
break is involved.

So the sequence there would be something like:
update X's requirements to Y >= 2
use new feature from Y >= 2 [ this is a 'feature' patch, not an api-break].
release X, and it should be a new major version.

Now, if Y is not exposed, a change in Y's dependencies for X clearly
has nothing to do with X's version... but users of X that
independently use Y will still be impacted, since upgrading X will
upgrade their Y [ignoring the intricacies surrounding pip here :)].

So, one answer we can use is "The version impact of a requirements
change is never less than the largest version change in the change."
That is:
nothing -> a requirement -> major version change
1.x.y -> 2.0.0 -> major version change
1.2.y -> 1.3.0 -> minor version change
1.2.3. -> 1.2.4 -> patch version change

We could calculate the needed change programmatically for this
approach in the requirements syncing process.

Another approach would be to say that only explicitly exposed
interfaces matter, but I think this is a disservice to our consumers.

A third approach would be to pick minor versions always as the
evolving process in the releases team does, but because requirements
changes *can* be API breaks to users of components, I think that that
is too conservative.

A fourth one would be to pick patch level for every change, but that
too is too conservative for exactly the same reasons.

-Rob

-- 
Robert Collins <rbtcollins at hp.com>
Distinguished Technologist
HP Converged Cloud