OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

Simon Spero
As Bertrand mentioned earlier, the bundle:baseline goal  is built in to the
maven-bundle-plugin already in use!

The pull-request adds that goal to the verify phase of the maven build (and
changes the travis config to run 'mvn verify'  instead of 'mvn test' ). The
baseline goal is set to fail the build if the versioning contains errors.

It takes very little work to bump the package version numbers when an API
change is made.  The first time you change a package in a way that requires
a new version number, the build will simply break in the verify phase, with
a list of changes, and a suggested new version number.

Any further API changes to the package at the same level or below will pass
the verify stage without a problem. For example, if you have already bumped
the package by a minor version, any further minor changes won't require any
more changes.

However, a subsequent major (breaking) changes will fail when verifying.
The author of the change can then consider whether the breaking change is
the best way forward, or whether their goals can be achieved in different
way.Studies have shown that there is considerable confusion about what is
and isn't a binary compatible change in java (for example, changing the
return type of a method from Collection<Foo> to List<Foo> is a
binary-incompatible change (but is source-compatible).  Breaking changes
need careful consideration.

In principle, the major and minor components of the bundle & artifact
version should be bumped to match the most significant change in any
package in the bundle/artifact, so that maven version-range dependencies
don't break, but that ship has sunk.

Simon
p.s.
The reason I'd been making changes to commons-compress was to support
creating and using random access tar.xz files in order to store release
series of  bundles from maven-central to investigate this issue (and see
how many problems can be fixed statically, and how many by dynamic
rewriting and/or fibbing.
p.p.s.
Compressing series of maven artifact is quite interesting ;
 for example, the ten releases of common-math3 (to 3.6) contain 40.9 MiB
 of uncompressed contents:

17.8 MiB as jars.
  6.4 MiB when the jars are packed in version order in .tar.xz format,
  4.4 MiB if the jars are run through pack200 and xz'ed individually.
  1.6 MiB if the compressed entries of the jar files are reflated first.
  1.5 MiB if run through pack200 then tar.xz
Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

garydgregory
On Wed, Jun 7, 2017 at 10:28 AM, Simon Spero <[hidden email]> wrote:

> As Bertrand mentioned earlier, the bundle:baseline goal  is built in to the
> maven-bundle-plugin already in use!
>
> The pull-request adds that goal to the verify phase of the maven build (and
> changes the travis config to run 'mvn verify'  instead of 'mvn test' ). The
> baseline goal is set to fail the build if the versioning contains errors.
>

We should run mvn verify anyway to pick up any other checks like
integration tests.

Gary


>
> It takes very little work to bump the package version numbers when an API
> change is made.  The first time you change a package in a way that requires
> a new version number, the build will simply break in the verify phase, with
> a list of changes, and a suggested new version number.
>
> Any further API changes to the package at the same level or below will pass
> the verify stage without a problem. For example, if you have already bumped
> the package by a minor version, any further minor changes won't require any
> more changes.
>
> However, a subsequent major (breaking) changes will fail when verifying.
> The author of the change can then consider whether the breaking change is
> the best way forward, or whether their goals can be achieved in different
> way.Studies have shown that there is considerable confusion about what is
> and isn't a binary compatible change in java (for example, changing the
> return type of a method from Collection<Foo> to List<Foo> is a
> binary-incompatible change (but is source-compatible).  Breaking changes
> need careful consideration.
>
> In principle, the major and minor components of the bundle & artifact
> version should be bumped to match the most significant change in any
> package in the bundle/artifact, so that maven version-range dependencies
> don't break, but that ship has sunk.
>
> Simon
> p.s.
> The reason I'd been making changes to commons-compress was to support
> creating and using random access tar.xz files in order to store release
> series of  bundles from maven-central to investigate this issue (and see
> how many problems can be fixed statically, and how many by dynamic
> rewriting and/or fibbing.
> p.p.s.
> Compressing series of maven artifact is quite interesting ;
>  for example, the ten releases of common-math3 (to 3.6) contain 40.9 MiB
>  of uncompressed contents:
>
> 17.8 MiB as jars.
>   6.4 MiB when the jars are packed in version order in .tar.xz format,
>   4.4 MiB if the jars are run through pack200 and xz'ed individually.
>   1.6 MiB if the compressed entries of the jar files are reflated first.
>   1.5 MiB if run through pack200 then tar.xz
>
Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

Simon Spero
So what's the current thinking on using compatibility-verified package
versioning  (for commons-* in general, but  COMPRESS-399 in particular?)

It doesn't take much work, and incorrect package versions cause real
problems.

*You added the headers and here I am. You tell 'em I'M coming... and Jar
Hell's coming with me, you hear?  **Jar Hell's coming with me!*


Simon

On Wed, Jun 7, 2017 at 5:02 PM, Gary Gregory <[hidden email]> wrote:

> On Wed, Jun 7, 2017 at 10:28 AM, Simon Spero <[hidden email]> wrote:
>
> > As Bertrand mentioned earlier, the bundle:baseline goal  is built in to
> the
> > maven-bundle-plugin already in use!
> >
> > The pull-request adds that goal to the verify phase of the maven build
> (and
> > changes the travis config to run 'mvn verify'  instead of 'mvn test' ).
> The
> > baseline goal is set to fail the build if the versioning contains errors.
> >
>
> We should run mvn verify anyway to pick up any other checks like
> integration tests.
>
> Gary
>
>
> >
> > It takes very little work to bump the package version numbers when an API
> > change is made.  The first time you change a package in a way that
> requires
> > a new version number, the build will simply break in the verify phase,
> with
> > a list of changes, and a suggested new version number.
> >
> > Any further API changes to the package at the same level or below will
> pass
> > the verify stage without a problem. For example, if you have already
> bumped
> > the package by a minor version, any further minor changes won't require
> any
> > more changes.
> >
> > However, a subsequent major (breaking) changes will fail when verifying.
> > The author of the change can then consider whether the breaking change is
> > the best way forward, or whether their goals can be achieved in different
> > way.Studies have shown that there is considerable confusion about what is
> > and isn't a binary compatible change in java (for example, changing the
> > return type of a method from Collection<Foo> to List<Foo> is a
> > binary-incompatible change (but is source-compatible).  Breaking changes
> > need careful consideration.
> >
> > In principle, the major and minor components of the bundle & artifact
> > version should be bumped to match the most significant change in any
> > package in the bundle/artifact, so that maven version-range dependencies
> > don't break, but that ship has sunk.
> >
> > Simon
> > p.s.
> > The reason I'd been making changes to commons-compress was to support
> > creating and using random access tar.xz files in order to store release
> > series of  bundles from maven-central to investigate this issue (and see
> > how many problems can be fixed statically, and how many by dynamic
> > rewriting and/or fibbing.
> > p.p.s.
> > Compressing series of maven artifact is quite interesting ;
> >  for example, the ten releases of common-math3 (to 3.6) contain 40.9 MiB
> >  of uncompressed contents:
> >
> > 17.8 MiB as jars.
> >   6.4 MiB when the jars are packed in version order in .tar.xz format,
> >   4.4 MiB if the jars are run through pack200 and xz'ed individually.
> >   1.6 MiB if the compressed entries of the jar files are reflated first.
> >   1.5 MiB if run through pack200 then tar.xz
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

garydgregory
My POV is that I only see a possible use cases for this in multi-module
components where one module defines an API and others different
implementation. Our release process is enough of a pain. Asking everyone to
consider if a change warrants a package version change is a pain. I still
do not see what practical and concrete problem this would solve for a
single module component. Granted COMPRESSA defines an API and
implementations all is one jar. But we work for 100% BC within a minor
release, so no problem there right? For BC breaks, we use a new version and
new package name, so no problem either, right?

Can you show us a real problem that this would have solved? If not, write
up a realistic imaginary problem?

Gary

On Jun 11, 2017 10:25 AM, "Simon Spero" <[hidden email]> wrote:

So what's the current thinking on using compatibility-verified package
versioning  (for commons-* in general, but  COMPRESS-399 in particular?)

It doesn't take much work, and incorrect package versions cause real
problems.

*You added the headers and here I am. You tell 'em I'M coming... and Jar
Hell's coming with me, you hear?  **Jar Hell's coming with me!*


Simon

On Wed, Jun 7, 2017 at 5:02 PM, Gary Gregory <[hidden email]> wrote:

> On Wed, Jun 7, 2017 at 10:28 AM, Simon Spero <[hidden email]> wrote:
>
> > As Bertrand mentioned earlier, the bundle:baseline goal  is built in to
> the
> > maven-bundle-plugin already in use!
> >
> > The pull-request adds that goal to the verify phase of the maven build
> (and
> > changes the travis config to run 'mvn verify'  instead of 'mvn test' ).
> The
> > baseline goal is set to fail the build if the versioning contains
errors.

> >
>
> We should run mvn verify anyway to pick up any other checks like
> integration tests.
>
> Gary
>
>
> >
> > It takes very little work to bump the package version numbers when an
API

> > change is made.  The first time you change a package in a way that
> requires
> > a new version number, the build will simply break in the verify phase,
> with
> > a list of changes, and a suggested new version number.
> >
> > Any further API changes to the package at the same level or below will
> pass
> > the verify stage without a problem. For example, if you have already
> bumped
> > the package by a minor version, any further minor changes won't require
> any
> > more changes.
> >
> > However, a subsequent major (breaking) changes will fail when verifying.
> > The author of the change can then consider whether the breaking change
is
> > the best way forward, or whether their goals can be achieved in
different
> > way.Studies have shown that there is considerable confusion about what
is

> > and isn't a binary compatible change in java (for example, changing the
> > return type of a method from Collection<Foo> to List<Foo> is a
> > binary-incompatible change (but is source-compatible).  Breaking changes
> > need careful consideration.
> >
> > In principle, the major and minor components of the bundle & artifact
> > version should be bumped to match the most significant change in any
> > package in the bundle/artifact, so that maven version-range dependencies
> > don't break, but that ship has sunk.
> >
> > Simon
> > p.s.
> > The reason I'd been making changes to commons-compress was to support
> > creating and using random access tar.xz files in order to store release
> > series of  bundles from maven-central to investigate this issue (and see
> > how many problems can be fixed statically, and how many by dynamic
> > rewriting and/or fibbing.
> > p.p.s.
> > Compressing series of maven artifact is quite interesting ;
> >  for example, the ten releases of common-math3 (to 3.6) contain 40.9 MiB
> >  of uncompressed contents:
> >
> > 17.8 MiB as jars.
> >   6.4 MiB when the jars are packed in version order in .tar.xz format,
> >   4.4 MiB if the jars are run through pack200 and xz'ed individually.
> >   1.6 MiB if the compressed entries of the jar files are reflated first.
> >   1.5 MiB if run through pack200 then tar.xz
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

Emmanuel Bourg-3
Le 11/06/2017 à 21:16, Gary Gregory a écrit :

> Can you show us a real problem that this would have solved?
+1, I don't understand what actual issue it would solve with
commons-compress.

Emmanuel Bourg

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

Simon Spero
In reply to this post by garydgregory
On Sun, Jun 11, 2017 at 3:16 PM, Gary Gregory <[hidden email]>
wrote:

> My POV is that I only see a possible use cases for this in multi-module
> components where one module defines an API and others different
> implementation. Our release process is enough of a pain. Asking everyone
> to consider if a change warrants a package version change is a pain. I still
> do not see what practical and concrete problem this would solve for a
> single module component. Granted COMPRESSA defines an API and
> implementations all is one jar. But we work for 100% BC within a minor
> release, so no problem there right? For BC breaks, we use a new version and
> new package name, so no problem either, right?
>
> Can you show us a real problem that this would have solved? If not, write
> up a realistic imaginary problem?
>

See: e.g http://www.sciencedirect.com/science/article/pii/S1571066111000399

Note that the specific versions of *org.apache.commons.fileupload *are not
completely on point, since as far as I know the first version of
commons-fileupload to include bundle headers was 1.2.1

However, we don't have to go much further to find more examples in that
series.
The bundles org.apache.commons.fileupload , version 1.2.*1*, and
 org.apache.commons.fileupload, version 1.2.*2*  use the  same  version
numbers for all packages, are two *micro* (aka bug-fix) version numbers
within the same micro version.  Under  semantic versioning rules, micro
versions must not have any API changes.

However, between those 1.2.1 and 1.2.2, there are *minor* level changes to
two of the five packages (the other three remain unchanged.
Moving from version 1.2.2 to version 1.3.0,  there are *major* breaking
binary changes to four packages (meaning they should have version 2.0.0).
From version 1.3.0 to 1.3.1 there are minor (backwards compatible changes)
to one package, with the other four having no API changes.
From 1.3.1 to 1.3.2 has no API changes, so is the micro version bump is
correct.

 Looking at commons-math, there were major breaking changes to 6 packages
between versions  2.0 and 2.1.
There were five more packages with major level changes between 2.1 and
2.2.  This was the second set of breaking changes for three of  of these
packages; their correct version number should have been 4.0.   Note that
this is *before* the packages prefix got changes to org.apache.commons.math3

The nature of the major changes in commons-math (mostly changing the return
types of methods) suggests that the developers might have used a different
approach rather than breaking binary compatibility.  To me, it seems that
automatically bumping the major version would have been the wrong response.


If you like, I can post a list of what the package version should have
been, assuming that every compatibility change was intentional, and
versioning was properly applied,  for  every bundle series under
org.apache.commons and commons-* that was on maven-central as of mid-may?

Simon
Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

garydgregory
Is one upshot of this is that we should base the version number based on
this OSGi report tool?

Gary

On Jun 11, 2017 1:58 PM, "Simon Spero" <[hidden email]> wrote:

> On Sun, Jun 11, 2017 at 3:16 PM, Gary Gregory <[hidden email]>
> wrote:
>
> > My POV is that I only see a possible use cases for this in multi-module
> > components where one module defines an API and others different
> > implementation. Our release process is enough of a pain. Asking everyone
> > to consider if a change warrants a package version change is a pain. I
> still
> > do not see what practical and concrete problem this would solve for a
> > single module component. Granted COMPRESSA defines an API and
> > implementations all is one jar. But we work for 100% BC within a minor
> > release, so no problem there right? For BC breaks, we use a new version
> and
> > new package name, so no problem either, right?
> >
> > Can you show us a real problem that this would have solved? If not, write
> > up a realistic imaginary problem?
> >
>
> See: e.g http://www.sciencedirect.com/science/article/pii/
> S1571066111000399
>
> Note that the specific versions of *org.apache.commons.fileupload *are not
> completely on point, since as far as I know the first version of
> commons-fileupload to include bundle headers was 1.2.1
>
> However, we don't have to go much further to find more examples in that
> series.
> The bundles org.apache.commons.fileupload , version 1.2.*1*, and
>  org.apache.commons.fileupload, version 1.2.*2*  use the  same  version
> numbers for all packages, are two *micro* (aka bug-fix) version numbers
> within the same micro version.  Under  semantic versioning rules, micro
> versions must not have any API changes.
>
> However, between those 1.2.1 and 1.2.2, there are *minor* level changes to
> two of the five packages (the other three remain unchanged.
> Moving from version 1.2.2 to version 1.3.0,  there are *major* breaking
> binary changes to four packages (meaning they should have version 2.0.0).
> From version 1.3.0 to 1.3.1 there are minor (backwards compatible changes)
> to one package, with the other four having no API changes.
> From 1.3.1 to 1.3.2 has no API changes, so is the micro version bump is
> correct.
>
>  Looking at commons-math, there were major breaking changes to 6 packages
> between versions  2.0 and 2.1.
> There were five more packages with major level changes between 2.1 and
> 2.2.  This was the second set of breaking changes for three of  of these
> packages; their correct version number should have been 4.0.   Note that
> this is *before* the packages prefix got changes to
> org.apache.commons.math3
>
> The nature of the major changes in commons-math (mostly changing the return
> types of methods) suggests that the developers might have used a different
> approach rather than breaking binary compatibility.  To me, it seems that
> automatically bumping the major version would have been the wrong response.
>
>
> If you like, I can post a list of what the package version should have
> been, assuming that every compatibility change was intentional, and
> versioning was properly applied,  for  every bundle series under
> org.apache.commons and commons-* that was on maven-central as of mid-may?
>
> Simon
>
Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

Matt Sicker
I'd love to have a semantic versioning plugin like that which can suggest
what the version number is for the entire project. Elm (programming
language) has a tool like that, and it works rather well in practice (even
though there are some popular libraries that are at version 5.0.0 already
because of it).

On 11 June 2017 at 18:37, Gary Gregory <[hidden email]> wrote:

> Is one upshot of this is that we should base the version number based on
> this OSGi report tool?
>
> Gary
>
> On Jun 11, 2017 1:58 PM, "Simon Spero" <[hidden email]> wrote:
>
> > On Sun, Jun 11, 2017 at 3:16 PM, Gary Gregory <[hidden email]>
> > wrote:
> >
> > > My POV is that I only see a possible use cases for this in multi-module
> > > components where one module defines an API and others different
> > > implementation. Our release process is enough of a pain. Asking
> everyone
> > > to consider if a change warrants a package version change is a pain. I
> > still
> > > do not see what practical and concrete problem this would solve for a
> > > single module component. Granted COMPRESSA defines an API and
> > > implementations all is one jar. But we work for 100% BC within a minor
> > > release, so no problem there right? For BC breaks, we use a new version
> > and
> > > new package name, so no problem either, right?
> > >
> > > Can you show us a real problem that this would have solved? If not,
> write
> > > up a realistic imaginary problem?
> > >
> >
> > See: e.g http://www.sciencedirect.com/science/article/pii/
> > S1571066111000399
> >
> > Note that the specific versions of *org.apache.commons.fileupload *are
> not
> > completely on point, since as far as I know the first version of
> > commons-fileupload to include bundle headers was 1.2.1
> >
> > However, we don't have to go much further to find more examples in that
> > series.
> > The bundles org.apache.commons.fileupload , version 1.2.*1*, and
> >  org.apache.commons.fileupload, version 1.2.*2*  use the  same  version
> > numbers for all packages, are two *micro* (aka bug-fix) version numbers
> > within the same micro version.  Under  semantic versioning rules, micro
> > versions must not have any API changes.
> >
> > However, between those 1.2.1 and 1.2.2, there are *minor* level changes
> to
> > two of the five packages (the other three remain unchanged.
> > Moving from version 1.2.2 to version 1.3.0,  there are *major* breaking
> > binary changes to four packages (meaning they should have version 2.0.0).
> > From version 1.3.0 to 1.3.1 there are minor (backwards compatible
> changes)
> > to one package, with the other four having no API changes.
> > From 1.3.1 to 1.3.2 has no API changes, so is the micro version bump is
> > correct.
> >
> >  Looking at commons-math, there were major breaking changes to 6 packages
> > between versions  2.0 and 2.1.
> > There were five more packages with major level changes between 2.1 and
> > 2.2.  This was the second set of breaking changes for three of  of these
> > packages; their correct version number should have been 4.0.   Note that
> > this is *before* the packages prefix got changes to
> > org.apache.commons.math3
> >
> > The nature of the major changes in commons-math (mostly changing the
> return
> > types of methods) suggests that the developers might have used a
> different
> > approach rather than breaking binary compatibility.  To me, it seems that
> > automatically bumping the major version would have been the wrong
> response.
> >
> >
> > If you like, I can post a list of what the package version should have
> > been, assuming that every compatibility change was intentional, and
> > versioning was properly applied,  for  every bundle series under
> > org.apache.commons and commons-* that was on maven-central as of mid-may?
> >
> > Simon
> >
>



--
Matt Sicker <[hidden email]>
Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

Simon Spero
In reply to this post by garydgregory
On Sun, Jun 11, 2017 at 7:37 PM, Gary Gregory <[hidden email]>
wrote:

> Is one upshot of this is that we should base the version number based on
> this OSGi report tool?
>

There are a few choices so the SEF upshot selector
<http://www.hkpro.com/index.php?option=com_content&view=article&id=129:the-trigger-groups&catid=4:special-topics&Itemid=5>
should
be set to Fun :-)

One group of choices revolve around the term "version number".   There are
a few different version numbers involved here.

   1. The Maven version number  (i.e. ${project.version} )
   2. The OSGI bundle version (i.e. the one in the  "Bundle-Version"
   manifest header).
   3. The package version for each exported package (e.g. the value of
   version in the manifest header below)
      - Export-Package: org.apache.common.weasels;version="1.1.0"

Another group of choices revolve around interpretations of the term "base".

   1. automatically applying all suggested version numbers, without further
   review (e.g. for maven, writing  goals for the packaging phases).
   2. executing the baseline goal during the verify stage, possibly failing
   the build if the versions contain errors (or warnings), possibly only
   reporting.

Another level  of choice  is whether to have  different policies for
different levels of change.

   -  For example, if the maven version is taken as a given, code could be
   written to restrict changes to the level implied by  the maven version
   change. Thus, micro releases would be failed if any API changes, minor
   versions would be failed if no API changes, or any  Major changes, were
   found.

Some specific decisions:

   1. Setting the maven-bump match the maximum API change.
      - Advantages: This gives appropriate behavior when maven version
      ranges are used (e.g. <version>[1.1,2)</version>).
      - Disadvantages: If the artifact contains a lot of unrelated
      functionality, this may unnecessarily affect dependents that
don't need to
      change. This is especially problematic if it's a major-level change.
   2. Requiring *all* package version numbers to match.
      - This either requires (1), or the addition of a new, manually set
      property
      - Advantages: Require-Bundle imports with ranges will work (however,
      these are not considered good practice)
      - Disadvantages: Packages with changes at a lower level than the
      maximum will nevertheless be treated as if they had the higher level of
      changes.
         - This can require redundant  versions of identical classes to be
         loaded (if the imported packages are not used in any exported packages)
         - This can cause a system to ignore an updated artifact containing
         fixes to packages it uses, solely because of changes to
package it does not
         use.
         - In the worst case, cause systems that would otherwise have been
         resolvable to fail (e.g if a bundle wants to import two
bundles that would
         otherwise have had compatible  ranges for a used package to
no longer have
         a compatible range).
      3. Having per-package versions:
      - This requires (e.g.) incrementing the version number in a
      package-info.java @Version annotation for the first change of a
given level
      for each release.
      - Advantages:
         - most precise package versions (obviously :-).
         - Avoids disadvantages in (2)
         - Lays groundwork for use of other package annotations
            - e.g.:  @Export annotation to indicate package is for export,
            with other packages considered private (could also be used
for jig-slaw)
         - Disadvantages:
         - Requires updating one or more version number  per release,
         either manually or automatically
         - If NOT (1), OSGI systems that make use of pax mvn / aether URLs
          (e.g. Apache Kafka ) may not work optimally (if a repository index is
         used, this is not a problem)
      4. Automatically incrementing per-package versions:
      - Advantages:
         - Does not require developer to edit package-info.java @Version
         annotation.
      - Disadvantages:
         - Does not require developer to edit package-info.java @Version
         annotation.  "*Wait - that's not backwards compatible*?"
         - Requires some Mojo (most suitable place would be in Apache Felix
         maven-bundle-plugin).
      5. Automatically initializing per-package versions:
      - Advantages:
         - Avoids having to manually create or edit a large number of
         packages. Allows a uniform policy to be set.
      - Disadvantages:
         - Requires a small amount of code (could be new goal, could be
         groovy or bash/perl script).

A big part of the decision comes down to how to handle breaking changes.
If there is a policy to reduce unintended API changes, then manually
bumping package versions if the API change is required is probably best.  A
failing  bundle:baseline can be thought of like a failing unit  test;
either there's a bug in the code (api change is wrong), or there's a bug in
the unit test (the @Version is wrong).  Automatically accepting all API
changes then seems a little like automatically adding an @Ignore to a
failing test case.

Looking forward, it is a useful starting point for thinking more carefully
about how packages and artifacts are structured - which parts of a  project
is the API, and what part is implementation; are API and implementation
classes mixed in the same package;  is a lot of unrelated functionality
mixed in to a package;  etc.

Adding bundle:baseline to the commons parent verify stage seems like a
sensible move regardless.  This should not replace japicmp, as they have
non-overlapping features. These goals  should replace CLIRR, which is
obsolete (so obsolete that won't run under jdk-9 because jdk 1.5 bytecode
is no longer supported) .
Simon
p.s.

It would definitely be nice if the Felix Maven Bundle Plugin were able to
auto add/update package-info.java files & @Version annotations, with
configurable policies (e.g. limit auto-bumps to micro/minor/major; use
maven project.version as limit; adjust maven project.version, etc.).
[I'm not sure quite how auto-adjusting maven version bumping should work in
multi-project builds (should all children be forced to the same version, or
should each sub-project have its own version, so that if there are no
changes made in a subproject, there needn't be a new artifact released). ]

That's an issue for a different tracker :-)
Simon
Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

Simon Spero
In reply to this post by Matt Sicker
On Mon, Jun 12, 2017 at 10:53 AM, Matt Sicker <[hidden email]> wrote:

> I'd love to have a semantic versioning plugin like that which can suggest
> what the version number is for the entire project. Elm (programming
> language) has a tool like that, and it works rather well in practice (even
> though there are some popular libraries that are at version 5.0.0 already
> because of it).


The bundle:baseline goal does this (it's at the start of the report).
Having  frequent major version bumps is a good thing if they are necessary
and the libraries are small (definitely better than having breaking changes
without the bump).
It's not as good as having *correct* semantic-version numbers of 1.4.0 :-)
Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

garydgregory
I think that the best way to see how this works is to provide a patch...
then we can see how it goes.

Gary

On Mon, Jun 12, 2017 at 10:18 AM, Simon Spero <[hidden email]> wrote:

> On Mon, Jun 12, 2017 at 10:53 AM, Matt Sicker <[hidden email]> wrote:
>
> > I'd love to have a semantic versioning plugin like that which can suggest
> > what the version number is for the entire project. Elm (programming
> > language) has a tool like that, and it works rather well in practice
> (even
> > though there are some popular libraries that are at version 5.0.0 already
> > because of it).
>
>
> The bundle:baseline goal does this (it's at the start of the report).
> Having  frequent major version bumps is a good thing if they are necessary
> and the libraries are small (definitely better than having breaking changes
> without the bump).
> It's not as good as having *correct* semantic-version numbers of 1.4.0 :-)
>
Reply | Threaded
Open this post in threaded view
|

Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request

Simon Spero
On Jun 13, 2017 1:48 PM, "Gary Gregory" <[hidden email]> wrote:

I think that the best way to see how this works is to provide a patch...
then we can see how it goes.


Gary-
  Can you clarify a few things:

What would you like to see patches for - the commons parent / related mojo
one or more  commons projects, the Felix maven-bundle-plugin, or some
combination thereof?

The changes which I submitted as a pull-request for COMPRESS-399¹ (as
amended) are on
commons-compress only. https://github.com/apache/commons-compress/pull/26

The net changes:

1. Update the version of the maven-bundle-plugin used.
2. Add the bundle:baseline goal to the verify phase.
3. Add a "provided" scope maven dependency on org.osgi:org.osgi.annotation:
for the  @Version annotation.
4. Override the parent bundle:manifest configuration, with no version in
the export-package (this would override any other source of version info).
5. Add initial package-info.java files to each non-empty package,
initialized to the previously released version.
6. Change the travis.yml configuration to execute mvn verify as the build
task.
7. Add  bundle:baseline-report goal to the site phase.

An example of additional work after  a subsequent api change is
https://github.com/apache/commons-compress/pull/27/commits/82405c13bd2688817108d3f2854387b3417a764d

Some of these changes can be lifted to the parent; the initial setup of
package-info.java @Version annotations requires some code.

Simon

¹ OK, I made the changes, created the issue, then submitted the
pull-request.


On Mon, Jun 12, 2017 at 10:18 AM, Simon Spero <[hidden email]> wrote:

> On Mon, Jun 12, 2017 at 10:53 AM, Matt Sicker <[hidden email]> wrote:
>
> > I'd love to have a semantic versioning plugin like that which can
suggest
> > what the version number is for the entire project. Elm (programming
> > language) has a tool like that, and it works rather well in practice
> (even
> > though there are some popular libraries that are at version 5.0.0
already
> > because of it).
>
>
> The bundle:baseline goal does this (it's at the start of the report).
> Having  frequent major version bumps is a good thing if they are necessary
> and the libraries are small (definitely better than having breaking
changes
> without the bump).
> It's not as good as having *correct* semantic-version numbers of 1.4.0 :-)
>