Been hacking through this today: current structure/status:
project: version-delta-api: not tied to any particular programming language, comparator which can be passed a listener, listener receive each delta as calculated -- can be passed ignore file ant include/exclude strings, defines severity: backwards-breaking, enhancement, and internal (for a no-op). project: java-version-delta: delta implementation understands java class/methods/fields etc, putting clirr style delta messages into an enum which doesn't have an dependency on clirr. project: artifact-file-util: look up artifacts, download them and read their contents. project: clirr-java-version-delta: implements java-version-delta, uses artifact-file-util. project: apache-version-standard: service returns recommend version number after comparing against the latest released version number, relies on listener to output api differences, and determine highest level of api change, to determine which version number to return. Currently building the system to prevent the use of buildnumber and qualifiers other than on snapshots, as nothing exists mentioning them in the apr http://apr.apache.org/versioning.html The apache portable runtime version standard does want the name of a library to include it's major version number, so for ubuntu/debian xerces look like: libxerces2-java_2.9.0-1_all.deb, with a similar pattern on the jar names. Not proposing doing anything about the naming, just noting the delta. Enforcing/Tracking deltas to the api and suggesting version numbers seems sufficient to me. soon a rule to wrap it all up.... The clirr plugin supports an edge case of a project being compared against several jar files, to determine the delta from the project to all the jars, I'm leaving method signatures in place to support this, but not currently target it for implementation in the enforcer rule. It's coming together, but only about 12 hours in, expect it'll take a another 30 hours or so as I had to reacquaint myself with the clirr-maven-plugin code which is highly coupled, making separating these projects out fairly tedious, especially the artifact-file-util which I hope can be used on similar projects to scala-version-delta, ruby-version-delta, etc. On to a proposal: Thinking of creating a @ClientImplements annotation to specify when an api expects a consumer (not a provider / implementation) of a library to have a class implement an interface or extend an abstract class. This would determine if a change to that interface (or abstract method add to class) is a backwards breaking change or an enhancement, the default would be to assume that a client of an artifact is not expected to implement and api/extend an abstract class making the change an enhancement. Though I'm wondering if developers where planning on running with something like <scope>implements</scope> briefly mentioned in this thread<http://mail-archives.apache.org/mod_mbox/maven-dev/201011.mbox/%3caanlkti=uv7rpgdcdne_sr11+gyhzjf74vkc11rvsh...@mail.gmail.com%3e> and what the intent might be: I dont' see how it could help (an api jar made entirely of interfaces could always provide an interface it expects a client --of an implementation of that api-- to implement). The listener interface in the version-delta-api I'm building is an example of this. I'm normally not a fan of framework annotations in code, but something like this annotation would help to more clearly define an api. Given how uncommon/onerous it is to demand client implement an interface (though maybe I shouldn't say this while proposing to expose a listener pattern over the version-delta-api) I don't think it would be overly demanding to ask a dev who want to use these versioning tools to track their projects use this kind of annotation. Potential the library could simply be told which annotation to look for, rather than providing a default annotation? Weighing options, Looking for feedback, ideas to make it better, etc.... Thanks, Rex On Fri, Nov 5, 2010 at 2:07 PM, Rex Hoffman <r...@e-hoffman.org> wrote: > Really, this is a question of how apache maven wants to approach the apache > version standard. I'm begin to believe it would be bad form to rely on a > mojo plugin to do this. It would also be inappropriate to build the > functionality into maven proper as well (as part of the > DefaultArtifactVersion) as other version standards may be used by an > organization. At least being a part of an official maven plugin gives it > more credence, and sets a path for supporting other competing version > standard support (if they exist). > > The version plugin probably shouldn't break a build. But maybe it should > be able to determine the next appropriate version based on the code and > apache version standards. A library that abstracts the mechanism used could > be helpful in this, which is probably something I should write that wraps > clirr. > > Back to the mojo though: > > I had reworked it. With in a week or two of the discussion > that occurred on the mojo mailing list. I had split the functionality into > multiple patches (I had added other functionality at the same time). > > The only remaining question as far, as I know, was whether I should create > a helper class for storing version numbers or use the > DefaultArtifactVersion. The last message in the thread was that I should > not rely on DefaultArtifactVersion, as it could potentially couple the > plugin to a particular version of maven. I took that to mean it should > continue to use the ApacheVersionNumber class that I had originally written > as any reliance on the DefaultVersionNumber could break functionality. > > Also, I believe an ApacheVersionNumber class should exist. Though it should > implement the ArtifactVersion interface, and exist outside of the clirr > plugin. > > When I saw my dependency-convergence-rule patch quickly applied to the > enforcer plugin (which several mojo devs felt was the right place for the > the apache version number functionality anyway) I reweighed the benefits of > building this into clirr. > > 1) Being part of enforcer probably means it's more likely to be noticed and > used. > 2) Clirr plugin seems stagnant and infrequently updated. > 3) Building a rule that happens to use clirr seems more maven like to me. > It's more declarative.... The devs using it wont care about the underling > functionality. > 4) Should animal sniffer or some other toolset later prove to be more > effective and flexible, we can change it without expecting devs to change > their poms. > 5) An underling apache version standard library could be used by multiple > plugins, not just to break the build -- but in the case of the version > plugin, update the version appropriately without the need for input. > > In short I think it's better to build maven's implementation of the apache > version standard than the clirr plugin's implementation of the apache > version standard. > > So the real question is then, how do apache maven team members want to > handle version standards. Right now they are silently ignored, no though is > put into handling milestone releases. Or release candidates. Or nightly > builds. A mess had been growing in the way spring and hibernate name there > releases, potential breaking version ranges. Apache maven is in a position > to encourage good behavior. I think this would help. > > I also believe the same kind or opportunity to create a source control > branch policy library exists in maven. Though it's benefits are not as > widely felt. > > When the release plugin doesn't need anywhere near as much input as it does > now, I'll feel like this work is done. > > Sorry for the long email. Just wanted to be as clear as I can on my > current reasonings, and see if the members agree. I wouldn't mind doing the > work, as long as it gets used. > > Rex > > > On Fri, Nov 5, 2010 at 12:08 PM, Stephen Connolly < > stephen.alan.conno...@gmail.com> wrote: > >> I thought you were going to rework the patch... >> >> If you have reworked the patch, then ping the d...@mojo list again... >> >> given that the feeling is that m-enforcer-p is not a good fit (because >> of phases) >> >> and given that v-m-p is not a good fit (because I'm going to insist >> that v-m-p does not have anything to do with failing the build), >> clirr-m-p is the natural home of your extended functionality... >> >> if you are providing a clean patch which uses a helper method to >> delegate to DefaultArtifactVersion, then I cannot see why this will >> not be applied >> >> -Stephen >> >> On 5 November 2010 18:53, Rex Hoffman <r...@e-hoffman.org> wrote: >> > Hmm... good point about the phase.... i'll have to think on that. We >> can >> > always have two executions for the plugin, or perhaps the plugin should >> > allow a rule to specify what phase it wants to be run in, thought that >> would >> > be harder to pull off. Though probably more correct. >> > >> > I have already written this version check as a patch for clirr. >> > The current maintainers just seem unwilling to adopt it. >> > See: http://jira.codehaus.org/browse/MCLIRR-33 >> > >> > Also have it compiled here: >> > >> https://www.e-hoffman.org/released/repo/org/codehaus/mojo/clirr-maven-plugin/2.3.0/ >> > >> > Usage is as simple as: >> > >> > <configuration> >> > >> <failBasedOnApacheVersionNumberStandard>true</failBasedOnApacheVersionNumberStandard> >> > <strictVersionNumber>true</strictVersionNumber> >> > </configuration> >> > >> > MNG-3826 is unnecessary, because the clirr plugin itself can make the >> > distinction, simply by looking at your current version number and all >> prior >> > released version. >> > >> > Also, from there it's not hard to ensure no visible changes on patch >> number. >> > >> > I do think I need to go in an change the behavior for interfaces. >> Currently >> > clirr thinks any change to an interface is backwards breaking... on the >> > assumption that every consumer of the jar will implement that interface. >> I >> > don't believe most developers work that way with interfaces anymore. >> In >> > general I think we work more like slf4j, where we define an API made of >> > interfaces in a jar. Some packages implement it (so the changes for >> them >> > force code changes -- which is to be expected and wont require checking >> > functionality.... they failed compile will tell the dev what's up). But >> > almost every other package just uses that API. So my code does have a >> known >> > bug I have to clean up. >> > >> > But again, the mojo devs have very little interest in this, and I'd >> rather >> > we have a apache version standard plugin that happens to use clirr, >> rather >> > than a clirr plugin that happens to enforce the apache version standard. >> > >> > Rex >> > >> > On Fri, Nov 5, 2010 at 3:32 AM, Mark Hobson <markhob...@gmail.com> >> wrote: >> > >> >> On 4 November 2010 18:28, Rex Hoffman <r...@e-hoffman.org> wrote: >> >> > Seems reasonable, build a helper library to run clirr and analyze >> it's >> >> > results, allow the clirr plugin to use it in it's existing manner, or >> by >> >> an >> >> > enforcer rule. >> >> > >> >> > That fact that it's clirr under the hood of that enforcer rule will >> be >> >> > completely abstracted. This will be a rule to enforce apache version >> >> > standard, that happens to use clirr. I'll write a clean api for it's >> >> > analysis provider (clirr). >> >> > >> >> > I know it'll be annoying, that's kinda the point. If your working on >> a >> >> > 1.1-SNAPSHOT and create a backwards breaking change, you have messed >> up. >> >> > The rule will tell the dev to correct the method, or bump the >> version >> >> > number to 2.0-SNAPSHOT. The real danger is a dev not being aware >> that >> >> they >> >> > have produced a backwards breaking change. Again, very helpful for >> apis. >> >> > >> >> > Given Brett's email today citing the desire for >> >> > >> >> > " >> >> > Configurable conflict resolution strategy - newest, oldest that >> satisfies >> >> > Enforcer rule to lock down above >> >> > Importance of specificity, not magic - break the build if conflicting >> >> > versions, not try and solve it >> >> > Be deterministic is maven's strength >> >> > " >> >> > >> >> > I think it's important we codify how maven wants devs to think about >> >> > versions. Right now it a snapshot or release. The ranges have vague >> >> > meaning at best, not knowing what version policy the project you >> depend >> >> on >> >> > follows. >> >> > >> >> > If you want to hold of the release until Monday, I will commit to >> having >> >> it >> >> > done and tested by then?? >> >> > >> >> > I think having the dependency-convergence rule and this rule will do >> a >> >> lot >> >> > for many organization that have or are adopting maven. I know it >> >> definitely >> >> > helped at the last place I worked. >> >> >> >> Enforcing no API breaking changes within minor versions has been on my >> >> wish list for a while too. My plan was to use the Clirr plugin in a >> >> profile that is only activated for minor versions. This latter point >> >> requires something like MNG-3826 though. >> >> >> >> Personally I feel that this check is beyond the scope of the enforcer. >> >> By default the enforcer runs at validate phase, way before classes >> >> are compiled for Clirr, so I'd feel happier achieving this in the >> >> verify phase using clirr:check. It is a hazy line between enforcer >> >> rules and other plugin goals, but I'd suggest using rules for (fast) >> >> environment and POM checks and other plugins for (slower) checks that >> >> require results of lifecycle phases. >> >> >> >> Mark >> >> >> >> --------------------------------------------------------------------- >> >> To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org >> >> For additional commands, e-mail: dev-h...@maven.apache.org >> >> >> >> >> > >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org >> For additional commands, e-mail: dev-h...@maven.apache.org >> >>
