karaf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Guillaume Nodet <gno...@apache.org>
Subject Re: [DISCUSS] Semantic versioning
Date Sat, 24 May 2014 18:38:47 GMT
Comments inline...


2014-05-24 11:35 GMT+02:00 Achim Nierbeck <bcanhome@googlemail.com>:

> Please find my comments below.
>
> Regards, Achim
>
> sent from mobile device
> Am 24.05.2014 00:57 schrieb "David Jencks" <david_jencks@yahoo.com>:
> >
> > Well, your description blurs the distinction between providers and
> consumers. Slightly more precisely
>
> Because I anticipated this kind of answer I copied the definition from
> semvers.org. :-)
>

In the case of OSGi, semantic versioning usually refers to
   http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf
I don't want to have individual versioning of bundles and end up with
non-aligned bundle versions.
In OSGi, the bundle version does not really carry semantics, it's mostly
the package version.
For non OSGi environment, there's no versioning of package, so the semantic
has to be carried by the jar version.
We don't really have this problem for Karaf.


> >
> > MAJOR changes signal a consumer-incompatible change
> > MINOR changes signal a provider-incompatible change
> > MICRO changes signal a change not visible in the API
> >
>
> I'm not sure about that last definition. Cause this would lead has into
> that exact definition of Guillaume. Just imagine us changing something
> internal. Because of released artefacts need to be unique we bump the micro
> version as it isn't a "provider-incompatible" change. That is why I prefer
> the other definition.
>
> > I don't understand Guillaumes original example (is this your point too
> Achim?).  Making an addition to a package at 4.0.0 will raise it to 4.1.0?
>  If not, what kind of addition are you (Guillaume) talking about?  I think
> both the changes would have to be bug fixes.
> >
>
> I think it is best to always increase the minor version if we have to bump
> the version, but my guess right now is that Guillaume feared the same
> implications that I fear in case we take the "non-blured" definition.
>

You're right that any addition to an exported interface should lead to a
minor increase, not micro, so my example is wrong.  But then, we have the
problem i tried to explain at minor version level.

We do have small api package changes in micro release of Karaf. Those are
compatible for users because Karaf is supposed to be the only implementor.
  So we could end up with a 4.1 package in version Karaf 4.1 and then
wanting to backport a new minor feature in Karaf 4.0.x, in which case we'd
need to also backport the new stuff that was added in 4.1.


>
> > I thinksSemantic versioning is really supposed to apply to a single
> unbranched stream of releases.  You can graft it onto some branched release
> structures but not all.  I think the problem is that a package at version
> 4.0.0 present in 2 branches can try to  get independent bug fixes in each
> branch.  But if they are really bug fixes and not api changes then it
> should be ok to share the bug fixes among all the branches so even if you
> have 2 copies in your version control they could be identical.
> >
>

Yes, I think that's correct.  It's not much of a problem for pure bug
fixes.  So the only restriction would be the one explained above which
might lead to either: not backporting an improvement, or backport the whole
changes from the latest released version of that package.


>
> I'm not sure I understood this correctly, but this mean we cant do this
> cause its to late for Karaf?
>

I don't think it's too late if we start with a major version increase such
as 4.0.0 for all packages in Karaf 4.


> On the other hand if this means we end up in the versioning hell of the
> Aries project, I'm strongly against using this versioning schema.
>

The main problem with Aries, it not package versionning, as it's mostly
invisible to users.  The problem for developers is the release cycle and
for users the fact that the different release cycle means that each bundle
needs to be tracked individually.  I agree I don't really want to go this
way.

Given David's point about my example, I think using semantic verisoning on
packages could work.  It means a few restrictions for backporting
improvements in a minor release though, but I'd think it's  worth it.

The most important thing to note is that the tooling should help us.  I
need to do further testing, but it should report a build error and stop if
the package change is incompatible with the version change.  The tool
supports specifying that an imported package will be implemented, i.e. the
rules for providers apply instead (so a stricter range is used when
importing).
The only potential limitation is when dealing with the above use case
(backport of an improvement).  In such a case, the tool won't automatically
find the correct version to compare to (it compares to the highest inferior
version by default).  We'd have to either compare with 4.1.0 version for
example or have a warning printed because the version is bumped too high,
but we'd have to deal with those use case with caution.


>
> > david jencks
> >
> > On May 23, 2014, at 2:38 PM, Achim Nierbeck <bcanhome@googlemail.com>
> wrote:
> >
> > > Hi Guillaume,
> > >
> > > I like the idea of using this plugin, and I also like the idea of
> semantic
> > > versioning. But I also share your concern about the strictness those
> > > versions could apply on us.
> > >
> > > One thing we really should be aware of, we might end up in the release
> hell
> > > of the apache aries.
> > > Another thing we should make sure, if we touch an API and do change it
> we
> > > (or actually any exported package) we should always increase the minor
> > > version, this way we don't run into that "lockin" you have mentioned
> > > regarding bugfix-version.
> > >
> > > If I understood semantic versioning right, this is the appropriate way.
> > >
> > > Given a version number MAJOR.MINOR.PATCH, increment the:
> > > MAJOR version when you make incompatible API changes,
> > > MINOR version when you add functionality in a backwards-compatible
> manner,
> > > and
> > > PATCH version when you make backwards-compatible bug fixes.
> > >
> > > so to get back to the previous ascii-art documentations ;)
> > >
> > > Instead of:
> > > | Karaf 4.0.0  |  Karaf 4.1.0 |
> > > |  abc-4.0.0    |  abc-4.0.1   |
> > >
> > > it should be:
> > > | Karaf 4.0.0  |  Karaf 4.1.0 |
> > > |  abc-4.0.0    |  abc-4.1.0   |
> > >
> > > in case of the API change or in case of no change:
> > >
> > > | Karaf 4.0.0  |  Karaf 4.1.0 |
> > > |  abc-4.0.0    |  abc-4.0.0   |
> > >
> > >
> > > regards, Achim
> > >
> > >
> > >
> > > 2014-05-23 16:19 GMT+02:00 Guillaume Nodet <gnodet@apache.org>:
> > >
> > >> First, we're talking about package versioning, not bundle versioning.
> > >> Those are independent and the bundle version is of little use (as
> usually
> > >> the requirement is on the package version using a range).
> > >> And this also only apply to *exported* packages.
> > >>
> > >> The main thing to consider is that the package content / version has
> to be
> > >> consistent, i.e. for a given package and version, the content of the
> > >> package should be the same in all branches.
> > >>
> > >> So it's perfectly valid to have
> > >>
> > >> | Karaf 4.0.0  |  Karaf 4.0.1 | Karaf 4.1.0 |
> > >> |  abc-4.0.0    |  abc-4.0.1   | abc-4.0.1    |
> > >>
> > >> as long as the content of the package abc in 4.0.1 and 4.1.0 are the
> same.
> > >> And that goes down to the implementation too, as the interface is the
> > >> contract really.
> > >>
> > >> The "problems" come when you have a modification which is small new
> > >> feature, but fully compatible.  For example, you add a  method to an
> > >> interface which is consumed by users (i.e. not implemented).  In that
> case,
> > >> the semantic versioning rules lead to raising the version from 4.0.0
> to
> > >> 4.0.1.  so let's say we release this in the 4.1.x branch.
> > >> If we later find a bug that require another modification of this
> interface,
> > >> we need to increase the package to 4.0.2 and release that package in
> both
> > >> 4.0.x and 4.1.x branches, meaning we also need to backport the new
> feature
> > >> added with the 4.0.1 package.
> > >>
> > >> Note that the whole scenario is questionable, as changing the api for
> a bug
> > >> fix might not be considered a bug fix anymore, but i think we had to
> do
> > >> that in the past, and I don't see how we could avoid that in the
> future.
> > >> If such a case happen, we'd have to decide on a case by case to either
> not
> > >> backport the bug that require an api change, or have to backport all
> api
> > >> changes (and related implementations).   That's why some projects
> end-up
> > >> actually having a separate release cycle for each bundle.
> > >>
> > >>
> > >>
> > >> 2014-05-23 14:09 GMT+02:00 Jamie G. <jamie.goodyear@gmail.com>:
> > >>
> > >>> I believe that last point needs to be a little clearer too ;)
> > >>>
> > >>> Forgive my attempt at ascii table:
> > >>>
> > >>> | Karaf 4.0.0  |  Karaf 4.1.0 |
> > >>> |  abc-4.0.0    |  abc-4.0.1   |
> > >>>
> > >>> Bug in abc is found, requiring a patch:
> > >>>
> > >>> | Karaf 4.0.1  |  Karaf 4.1.0 | Karaf 4.1.1 |
> > >>> |  abc-4.0.2    |  abc-4.0.1   | abc-4.0.2    |
> > >>>
> > >>> Would the above table describe the releases?
> > >>>
> > >>> Why can't we have the following, where abc-4.0.1 are the same bug fix
> > >>> release?
> > >>>
> > >>> | Karaf 4.0.0  |  Karaf 4.0.1 | Karaf 4.1.0 |
> > >>> |  abc-4.0.0    |  abc-4.0.1   | abc-4.0.1    |
> > >>>
> > >>> Cheers,
> > >>> Jamie
> > >>>
> > >>> On Thu, May 22, 2014 at 11:31 AM, Guillaume Nodet <gnodet@apache.org
> >
> > >>> wrote:
> > >>>> A recent contribution to the felix maven-bundle-plugin is that
> baseline
> > >>>> goal which checks and/or reports semantic versioning changes.
> > >>>> It basically does a binary diff with the latest release of the
same
> > >>>> artifact for changes and verify that the changes are compatible
with
> > >> the
> > >>>> semantic versioning rules.
> > >>>>
> > >>>> I think we should try to leverage those, but without changing our
> > >> release
> > >>>> lifecycle.  This could be done the following way:
> > >>>>  * keep our artifacts versioning and release mechanism untouched
> > >>>>  * add the baseline plugin
> > >>>>  * in 4.0, exported packages would all have a version of 4.0.0
> > >>>>  * follow semantic versioning for all releases > 4.0
> > >>>>
> > >>>> This would mean that karaf 4.1 would have packages in version 4.0,
> > >> 4.0.1
> > >>> or
> > >>>> 4.1.  Note that the version used for karaf (and for bundles) isn't
> tied
> > >>> in
> > >>>> any way to the version of the packages.
> > >>>> But this would also help making sure we stay compatible, and
> whenever
> > >> we
> > >>> do
> > >>>> a new release (be it 4.1 or 5.0), help users with migration because
> the
> > >>>> package versions would not be changed unless needed.
> > >>>>
> > >>>> Downsides:
> > >>>>  * users may be impacted in the future with the fact that not all
> > >>> packages
> > >>>> have the same version, but this should usually be minor, as tools
> > >> usually
> > >>>> grab the version of the packages from the binary when writing an
> import
> > >>>> package.  However, for those which do not leverage those features,
> this
> > >>>> will have an impact
> > >>>>  * bug fix releases may be more tricky : the main problem is that
> with
> > >>>> semantic versioning, once a package is released with a minor
> upgrade,
> > >>>> there's no room left
> > >>>>
> > >>>> The last point needs an explanation.  Let's say we have a package
in
> > >>>> version 4.0.0 in karaf 4.  We later release karaf 4.1 with a very
> minor
> > >>>> addition to that package, so that this package is now in version
> 4.0.1.
> > >>> If
> > >>>> we later find  a bug which require a fix, we won't be able to
> release a
> > >>>> karaf 4.0.1 with a micro change in that package, so we'd have to
at
> > >> least
> > >>>> backport the interface change from 4.1 in 4.0.1 (even if we don't
> > >>> backport
> > >>>> the implementation) and then do the fix with a 4.0.2 package
> version.
> > >>>>
> > >>>> Not sure this is very clear, but the last point has always been
my
> > >> worry
> > >>>> about semantic versioning.
> > >>>>
> > >>>> Thoughts ?
> > >>>>
> > >>>> Guillaume
> > >>>
> > >>
> > >
> > >
> > >
> > > --
> > >
> > > Apache Karaf <http://karaf.apache.org/> Committer & PMC
> > > OPS4J Pax Web <http://wiki.ops4j.org/display/paxweb/Pax+Web/>
> Committer
> &
> > > Project Lead
> > > blog <http://notizblog.nierbeck.de/>
> > >
> > > Software Architect / Project Manager / Scrum Master
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message