On Sun, Jun 11, 2017 at 7:37 PM, Gary Gregory <garydgreg...@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
