[hibernate-dev] Explaining versioning and dependency compatibility

Tue Jul 15 06:27:37 EDT 2014

Interesting points. Indeed the need of users is different for the
Validator, Search, OGM examples, we might not be needing a "fits all"
solution.

So for OGM a BOM file might be useful. You should probably add all
other optional projects in there as well, that would resolve the
"intersections" problem.

For Validator, I don't understand why you all say there is no
dependency: it might be a wide range, but there is integration code in
ORM which has not always be there, and not always the same. I don't
expect Validator 3.x to work with latest ORM, and you should state
that somewhere.
On top of this, Validator has some shared dependencies with the other
modules; most of these are usually not a problem but there are
situations in which some combo might not work because of say a
breaking change int JBoss Logger or Commons Annotations.

Indeed for Search one might want to simply add some very basic
full-text search capability on an existing complex ORM application and
not wish to change ORM, or in a different case one wants to play with
the latest power features in the latest Search version. Depending on
the case one searches for compatibility for a specific version of ORM
or for a particular version of Search. I think it would be nice if
both project had some kind of informational box close to the version
details to list which "recommended" compatible version we suggest.

Even for OGM if we do BOM files, I would still like to see such an
information box on the website as not everyone is versed with Maven.

On 15 July 2014 09:10, Gunnar Morling <gunnar at hibernate.org> wrote:
> 2014-07-14 16:38 GMT+02:00 Sanne Grinovero <sanne at hibernate.org>:
>
>> On 14 July 2014 15:23, Gunnar Morling <gunnar at hibernate.org> wrote:
>> > 2014-07-14 12:54 GMT+02:00 Sanne Grinovero <sanne at hibernate.org>:
>> >
>> >> Good point on OGM' s need for a specific micro. We could propose a 4.4
>> >> series of ORM after you finish defining the integration point? So OGM
>> >> x.Final will be able to depend on a more reasonable version range.
>> >
>> >
>> > Yes, that'd be vey nice.
>> >
>> >>
>> >> About BOM files, I'm just skeptical as I don't see how we should
>> >> maintain and test them:
>> >
>> >
>> > We'd maintain it in the same way as we maintain the dependencyManagement
>> > block in our current POMs. Only that it's not part of the parent POM
>> > itself
>> > but is extracted into a separate POM file. We'd import that BOM in our
>> > own
>> > build and thus verify and test it.
>> >
>> > The significant difference would be that a user can do the same (import
>> > that
>> > BOM) and thus get matching versions of our artifacts.
>> >
>> >>
>> >> - would we update some separate BOM project at every release?
>> >
>> >
>> > It would be just a module of each project, e.g. hibernate-ogm-bom, which
>> > gets released as all the other modules.
>> >
>> >>
>> >> - would you re-run the testsuite of each and all projects at every BOM
>> >> update overriding the testsuite versions to make sure it's a valid
>> >> combination? (how to automate?)
>> >>
>> >> - I'd also expect some integration tests to actually verify the
>> >> correctness of the BOM file (e.g. syntax)
>> >
>> >
>> > See above, as the BOM would be used in a project's build itself, it gets
>> > verified.
>>
>> I don't understand how this would work. Let's take Search for example,
>> so I'd maintain a BOM file in Hibernate Search, and release a new one
>> at each of Search releases?
>
>
> Yes.
>
> You implicitly do the same also today by releasing your parent POM which
> contains the versions of the required ORM etc. modules. Only that a user
> cannot easily make use of those versions when declaring a dependency to ORM
> or any of the Search dependencies themselves.
>
>>
>> That implies my BOM file is "the one for Hibernate Search version X",
>> not for all projects together.
>> This doesn't answer the question of users "which version of Hibernate
>> Validator, Hibernate ORM, Hibernate Search work fine together? "
>
>
> It depends on the perspective. It answers the question "Which is the right
> version of ORM, if I want to work with release XYZ of Search?" What it does
> not answer is "If I'm working with ORM version XYZ, which version of Search
> do I need to add?".
>
> Maybe the situation is also a bit different for Search and OGM. I guess
> Search more often is added to projects which are using ORM already and thus
> need to find out the matching Search version (unless they are willing to
> switch to another ORM version and just take the latest Search). For OGM I'd
> rather expect that users start with the latest version of OGM and are fine
> with whatever ORM version this requires (at least until we truly support
> polyglot scenarios, where again OGM may be added to an existing ORM
> application).
>
> So at least for OGM a BOM as I described it would be very helpful. E.g. the
> user in the forum would have benefitted from it as he wouldn't have to
> manually specify ORM versions but would get those declared in the OGM BOM.
>
> As Hardy is saying, Validator has no version requirements in this context.
>
>> Let's say we release multiple BOM files. How do I use those in my
>> project, which one do I use to define my version of ORM?
>
>
> You'd have to use the one of the "most downstream" Hibernate project you're
> using. E.g. when working with ORM and Search, the one from Search. When
> working with ORM, Search and OGM, the one from OGM. BOMs can also include
> other BOMs, so e.g. in the OGM BOM we could import the one from Search, so
> we wouldn't have to re-declare versions for all Search components in OGM.
>
>>
>> As far as I know there is no such thing as "import the union of
>> multiple BOMs, validating the intersection is consistent" in Maven.
>
>
> Unfortunately that's true. I hoped the DependencyConvergence rule for the
> enforcer plug-in would help, but this one only deals with resolved
> dependencies and not things declared in <dependencyManagement>. So if a user
> would import the Search *and* the OGM BOM (which they shouldn't), there'd be
> a risk of inconsistencies (in this case the import declared first takes
> precedence).
>
> Nevertheless I feel that (at least for OGM) providing such BOM would be
> beneficial to users.
>
>> Sanne
>
>
> --Gunnar
>
>>
>>
>>
>>
>> >
>> >>
>> >> Also the documented dependency ranges on the website could need some
>> >> testing in a perfect world, but:
>> >> a) I'd expect it to be simpler as it' s a smaller matrix if each
>> >> project documents its own dependencies only
>> >> b) each project somehow "is aware" if when it breaks compatibility
>> >> with older dependencies, like you notice now with OGM: it's an
>> >> explicit step you just have to remember to document (and rare enough
>> >> so that I wouldn't bother too much to automate).
>> >> c) *Personal opinion* I feel like a statement about *expected
>> >> compatibility* does create a lower expectation in terms of accuracy
>> >> than a BOM file, so that I wouldn't expect need for actual QA on this
>> >> subject as much as I would expect it on BOM files which we would
>> >> officially distribute.
>> >
>> >
>> > Atm. we also specify which version of our dependencies we expect (in our
>> > parent POMs). So this information is there, it's only very hard for
>> > users to
>> > extract it if they want to add any of our dependencies themselves
>> > (they'd
>> > have to look up the version we depend on to make sure they don't
>> > override it
>> > with a non-compatible one). By giving users the BOMs for importing, this
>> > information is much more conveniently accessible (and there is no risk
>> > for
>> > it of getting out-dated as with a wiki/web site based approach).
>> >>
>> >>
>> >> I'm not strictly against BOM but it sounds like taking a lot of our
>> >> bandwidth for a minor practical improvement.
>> >
>> >
>> > Maybe we have different things in mind?
>> >
>> > It's not a huge effort, actually I've just pushed a branch for this for
>> > OGM:
>> >
>> > https://github.com/gunnarmorling/hibernate-ogm/compare/hibernate:master...gunnarmorling:OGM-574?expand=1
>> >
>> >> Ultimately we should be very aware that our modules are in constant
>> >> change, and people mixing our latest are aware of a little bit of risk
>> >> in using latest as there is a mismatch between our expectations vs our
>> >> capacity to test and deliver a single unified platform, I think that's
>> >> more something for assemblies such as WildFly, JBoss EAP, Spring, and
>> >> whoever else redistributes our jars as a combination. We should be
>> >> ready to provide recommendations (as what we expect to work) to the
>> >> people making these distributions and our users but.. would you
>> >> consider untested BOM files to be good for that?
>> >
>> >
>> > They are not untested (at least in my model), as they are used for our
>> > own
>> > build.
>> >
>> >> Sanne
>> >
>> >
>> > --Gunnar
>> >
>> >>
>> >> On 14 July 2014 11:21, Gunnar Morling <gunnar at hibernate.org> wrote:
>> >> > 2014-07-13 14:47 GMT+02:00 Sanne Grinovero <sanne at hibernate.org>:
>> >> >
>> >> >> I've been explaining $subject to a forum user [1]. I'm confident
>> >> >> it's
>> >> >> only a problem for newcomers, but are we expecting more expert
>> >> >> developers to pass this lore by word of mouth?
>> >> >
>> >> >
>> >> > Not so sure whether it's not a problem for expert users as well every
>> >> > now
>> >> > and then.
>> >> >
>> >> > Looking at OGM for instance, we're currently in the situation that we
>> >> > depend
>> >> > on a specific micro version of ORM (4.3.6 once it's out), which may
>> >> > be a
>> >> > surprising fact. Personally, I think it'd be rational for a user to
>> >> > expect
>> >> > compatibility based on minor version families of our projects, e.g.
>> >> > that
>> >> > each OGM 4.1.x release is compatible with each ORM 4.3.x release.
>> >> >
>> >> > As we can't guarantee this due to the rapid evolvement atm. (e.g. we
>> >> > add
>> >> > new
>> >> > SPIs in ORM micro releases for the sake of OGM), some clear
>> >> > documentation is
>> >> > highly desirable.
>> >> >
>> >> >> I think we should add an explanation on these on the website but I'm
>> >> >> not sure where this would be more appropriate to present.
>> >> >>
>> >> >> Should we highlight compatible versions of other integration points
>> >> >> on
>> >> >> each sub section?
>> >> >> For example I could edit the Search area to mention which versions
>> >> >> of
>> >> >> ORM, OGM, Lucene, Validator, Envers, Infinispan(we might have two
>> >> >> different ones!), Commons Annotations, etc.. are supposed to work
>> >> >> for
>> >> >> each release.
>> >> >
>> >> >
>> >> > Documenting the matching/required versions of upstream projects in
>> >> > each
>> >> > project area may be one way. E.g. Search could document its
>> >> > requirements,
>> >> > OGM its own etc. I don't think Search should document any
>> >> > expectations
>> >> > towards OGM versions as the dependency is the other way around?
>> >> >
>> >> > Speaking in Maven terms, I still think that providing this
>> >> > information
>> >> > in
>> >> > form of bill-of-materials POMs would be the approach most helpful to
>> >> > users.
>> >> > Such project BOM would contain the versions of all its components and
>> >> > dependencies. Users would reference this BOM using the "import" scope
>> >> > in
>> >> > their dependency management configuration and thus get matching
>> >> > versions
>> >> > when declaring a dependency to any of the artifacts listed in the
>> >> > BOM.
>> >> >
>> >> > I vaguely remember though that in the past there had been
>> >> > reservations
>> >> > towards providing such BOMs?
>> >> >
>> >> > @Davide, I've created https://hibernate.atlassian.net/browse/OGM-574
>> >> > to
>> >> > do
>> >> > this for OGM; Shall we give it a try?
>> >> >
>> >> > --Gunnar
>> >> >
>> >> >
>> >> >>
>> >> >> [1] https://forum.hibernate.org/viewtopic.php?f=31&t=1035292
>> >> >>
>> >> >> -- Sanne
>> >> >> _______________________________________________
>> >> >> hibernate-dev mailing list
>> >> >> hibernate-dev at lists.jboss.org
>> >> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>> >> >
>> >> >
>> >
>> >
>
>