Open Stack

Excerpts from Robert Collins's message of 2015-09-22 15:16:26 +1200:
> 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'.

Also, for our projects, "is this requirements change being triggered by
a need in some other project that also syncs with the g-r list"?

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

We also have to consider that we can't assume that the dependency
is using semver itself, so we might not be able to tell from the
outside whether the API is in fact breaking. So, we would need something
other than the version number to make that determination.

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

I've been encouraging the application of a simple rule precisely
because this problem is so complicated. The 4 reasons for updates
can get lost over time between a requirements update landing and a
release being created, especially with automatic updates mixing
with updates a project actually cares about.  We aren't yet correctly
identifying our own API breaking changes and differentiating between
features and bug fixes in all cases, so until we're better at that
analysis I would rather continue over-simplifying the analysis of
requirements updates.

Doug