Re: [openstack-dev] [releases] semver and dependency changes

[Thierry Carrez]

Robert Collins wrote:
> On 23 September 2015 at 02:03, Thierry Carrez  wrote:
>> Robert Collins wrote:
>>> [...]
>>> 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
>>
>> That feels a bit too much. In a lot of cases, the added requirement will
>> be used in a new, backward-compatible feature (requiring y bump), or
>> will serve to remove code without changing functionality (requiring z
>> bump). I would think that the cases where a new requirement requires a x
>> bump are rare.
> 
> So the question is 'will requiring this new thing force any users of
> the library to upgrade past a major version of that new thing'. If its
> new to OpenStack, then the answer is clearly no, for users of the
> library within OpenStack, but we don't know about users outside of
> OpenStack'. I am entirely happy to concede that this should be case by
> case though.
> 
>>> 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
>>
>> The last two sound like good rules of thumb.
> 
> What about the one you didn't comment on ? :)

Damn, you got me. Hmm... "it depends" ? I think we can't really have a
default rule for a major bump. Depending on how the library is used, it
could trigger anything. Defaulting to a major bump as a result sounds a
bit overkill.

-- 
Thierry Carrez (ttx)

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [releases] semver and dependency changes

[Robert Collins]

On 23 September 2015 at 02:48, Jeremy Stanley  wrote:
> On 2015-09-22 15:16:26 +1200 (+1200), Robert Collins wrote:
> [...]
>> 'Is this requirements change an API break' or 'is this requirements
>> change feature work' or 'is this requirements change a bugfix'.
> [...]
>
> It may also be worth considering whether this logic only applies to
> increasing minimums (and perhaps in some very rare cases, lowering
> maximums). Raising or removing a maximum (cap) or lowering a minimum
> further means that downstream consumers are expected to still be
> able to continue using the same dependency versions as before the
> change, which means at worst a patchlevel increase in the next
> release.

Ah yes - I was only analyzing minimums, but indeed, similar logic can
be applied to maximums and the constraints they place on consumers.

-Rob

-- 
Robert Collins 
Distinguished Technologist
HP Converged Cloud

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [releases] semver and dependency changes

[Robert Collins]

On 23 September 2015 at 00:43, Doug Hellmann  wrote:
> 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"?

I don't think that maps to semver though: which is why I didn't list
it. I agree that the /reason/ for a change may be 'consistency with
other OpenStack projects'. Until we've finished fixing up the pip
facilities around resolution we can't really make the requirements
syncing process more flexible - and even then its going to be really
very tricky [e.g. how do you test 'oslo.messaging works with
oslo.config version X when some other thing in devstack needs version
Y > X] - proving individually varied lower bounds is going to be
awkward at best if it depends on integration tests.
...
>> 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.

Agreed - while its unusual, a project can do both of major version
bumps without backwards incompatibilities, and minor or patch version
bumps that do include [deliberate] backwards incompatibilities.

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

So how about we [from a releases perspective] just don't comment on
requirements syncs - let projects make their own assessment?

I don't think 'pick minor' is a very useful heuristic - for many of
our 0.x.y projects we're overstating the impact [since x here is
major-before-stable-has-happened], for consumers of those we're
underestimating.

-Rob

-- 
Robert Collins 
Distinguished Technologist
HP Converged Cloud

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [releases] semver and dependency changes

[Robert Collins]

On 23 September 2015 at 02:03, Thierry Carrez  wrote:
> Robert Collins wrote:
>> [...]
>> 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
>
> That feels a bit too much. In a lot of cases, the added requirement will
> be used in a new, backward-compatible feature (requiring y bump), or
> will serve to remove code without changing functionality (requiring z
> bump). I would think that the cases where a new requirement requires a x
> bump are rare.

So the question is 'will requiring this new thing force any users of
the library to upgrade past a major version of that new thing'. If its
new to OpenStack, then the answer is clearly no, for users of the
library within OpenStack, but we don't know about users outside of
OpenStack'. I am entirely happy to concede that this should be case by
case though.

>> 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
>
> The last two sound like good rules of thumb.

What about the one you didn't comment on ? :)

-Rob

-- 
Robert Collins 
Distinguished Technologist
HP Converged Cloud

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [releases] semver and dependency changes

[Doug Hellmann]

Excerpts from Robert Collins's message of 2015-09-23 06:40:19 +1200:
> On 23 September 2015 at 00:43, Doug Hellmann  wrote:
> > 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"?
> 
> I don't think that maps to semver though: which is why I didn't list
> it. I agree that the /reason/ for a change may be 'consistency with
> other OpenStack projects'. Until we've finished fixing up the pip
> facilities around resolution we can't really make the requirements
> syncing process more flexible - and even then its going to be really
> very tricky [e.g. how do you test 'oslo.messaging works with
> oslo.config version X when some other thing in devstack needs version
> Y > X] - proving individually varied lower bounds is going to be
> awkward at best if it depends on integration tests.
> ...
> >> 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.
> 
> Agreed - while its unusual, a project can do both of major version
> bumps without backwards incompatibilities, and minor or patch version
> bumps that do include [deliberate] backwards incompatibilities.
> 
> > 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.
> 
> So how about we [from a releases perspective] just don't comment on
> requirements syncs - let projects make their own assessment?

Most folks can't follow the relatively simple rules we have for
that now. We regularly have requests for patch releases for libs with
new features (with commit messages like "Add fancy new blah blah
feature") and we have, at least once, completely missed a backwards
incompatibility that required a major version bump.

> 
> I don't think 'pick minor' is a very useful heuristic - for many of
> our 0.x.y projects we're overstating the impact [since x here is
> major-before-stable-has-happened], for consumers of those we're
> underestimating.

Our use of these versioning rules is relatively new, and everyone
is still figuring it out.  I've been trying to encourage
simple-to-understand interpretations for all of the rules so we're
at least consistent, if not 100% correct. For requirements changes,
I considered that since one could not simply install the new version
of the library without also updating its dependencies, it was not
a patch release. And since the requirements updates haven't been
backwards-incompatible (as far as I have been able to tell in most
cases), they didn't require a major version update. So, the minor
version seemed right. That also produced a rule we could evaluate
for the case where the project itself did not request the requirements
update which, as you point out, isn't covered by semver directly.

Doug

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [releases] semver and dependency changes

[Thierry Carrez]

Robert Collins wrote:
> [...]
> 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

That feels a bit too much. In a lot of cases, the added requirement will
be used in a new, backward-compatible feature (requiring y bump), or
will serve to remove code without changing functionality (requiring z
bump). I would think that the cases where a new requirement requires a x
bump are rare.

> 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

The last two sound like good rules of thumb.

-- 
Thierry Carrez (ttx)

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [releases] semver and dependency changes

[Jeremy Stanley]

On 2015-09-22 15:16:26 +1200 (+1200), Robert Collins wrote:
[...]
> 'Is this requirements change an API break' or 'is this requirements
> change feature work' or 'is this requirements change a bugfix'.
[...]

It may also be worth considering whether this logic only applies to
increasing minimums (and perhaps in some very rare cases, lowering
maximums). Raising or removing a maximum (cap) or lowering a minimum
further means that downstream consumers are expected to still be
able to continue using the same dependency versions as before the
change, which means at worst a patchlevel increase in the next
release.
-- 
Jeremy Stanley

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [releases] semver and dependency changes

[Doug Hellmann]

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

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [releases] semver and dependency changes

[Robert Collins]

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 
Distinguished Technologist
HP Converged Cloud

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev