commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Simon Spero <sesunc...@gmail.com>
Subject Re: OSGI Version at Package Level : some more details about the COMPRESS-399 pull request
Date Mon, 12 Jun 2017 17:09:12 GMT
On Sun, Jun 11, 2017 at 7:37 PM, Gary Gregory <garydgregory@gmail.com>
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

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