[hibernate-dev] [NoORM] A simpler README.md?

[Yoann Rodiere]

Hi everyone,

TL;DR: I would like to strip down the README in Hibernate Search to
redirect users to the website, which is better suited for presenting
available versions, and helping users to get started. See what I mean in this
PR . Any
objections?

Currently, the README.md in NoORM projects duplicates a bit of information
from our website and documentation:

   - The version number and date of the latest release:
   https://github.com/hibernate/hibernate-search#hibernate-search vs.
   http://hibernate.org/search/releases/
   - A description of the project:
   https://github.com/hibernate/hibernate-search#description vs.
   http://hibernate.org/search/
   - The requirements:
   https://github.com/hibernate/hibernate-search#requirements vs.
   http://hibernate.org/search/releases/#compatibility-matrix or
   http://hibernate.org/search/releases/5.10/#compatibility
   - Installation instructions:
   https://github.com/hibernate/hibernate-search#maven +
   https://github.com/hibernate/hibernate-search#sourceforge-bundle vs.
   http://hibernate.org/search/releases/5.10/#get-it or
   http://hibernate.org/search/documentation/getting-started/


Some of this information is updated manually when we don'r forget about it,
and some of it (the latest release) is updated automatically when we
perform a release on master.

As a result, from time to time the information is not in sync. Right now,
in Search, the version displayed in the README is 5.10.0.Final, whereas the
latest release is 5.10.1.Final and the master branch hosts the
5.11.0-SNAPSHOT code. This is because the release scripts do not update
master when we release from another branch, and we have to do it manually
(that's expected: doing otherwise would be too complex).

Also, the information is partial:

   - the README currently completely hides the fact that other Hibernate
   Search versions are still maintained and can work well with older versions
   of Hibernate ORM.
   - whenever the latest release is an alpha/beta/CR, we usually display
   installation instructions for the latest development version, and
   completely hide information about the latest stable version.

What's worse, keeping the documentation on branch master the README on
branch master may prove confusing: the README refers to the latest release,
but the rest of the code may have been updated since the latest release,
sometimes significantly so. We will have trouble dealing with this when we
merge Hibernate Search 6, in particular.

We may not agree on what is the best solution, but let's at least agree
this is not ideal, especially when it comes to informing users about the
stable version they want to use.

We could put in more effort, try our very best to keep everything in sync
and as complete as possible/necessary. Add more documentation about the
release process. Try our best to do less mistakes. We could. But obviously,
nobody is perfect, and so never will this README.

Other projects, such as Spring Boot (
https://github.com/spring-projects/spring-boot) or, more relevantly,
Hibernate ORM (https://github.com/hwithibernate/hibernate-orm
), simply do not refer to the
latest version in their README, and redirect to their website for all
version-specific information. The README focuses on presenting the project,
redirecting users to the website, and giving contributor-friendly
information.

I find this solution both elegant and powerful. Presenting the project is
always necessary, but guiding users to the right version and giving getting
started instructions is something complex, and something we already do on
our website. So why not redirect people there? All links stay valid and
relevant as long as the website is up and kept updated, and the impact of
maintainers forgetting to update the README is far smaller. One less thing
to worry about for maintainers, and better guidance for prospective users.

A simple link to the getting started guide could be enough for most users,
but we can go a step further and offer additional links. I just sent a pull
request to show how I see it implemented in Search; please let me know what
you think.
The PR: https://github.com/hibernate/hibernate-search/pull/1692
Preview of the README as seen from the GitHub web view:
https://github.com/yrodiere/hibernate-search/blob/ae4d347fa4c647a3c5ddb6f43412cf3dce0e354e/README.md

Cheers,
-- 
Yoann Rodiere
yo...@hibernate.org / yrodi...@redhat.com
Software Engineer
Hibernate NoORM team
___
hibernate-dev mailing list
hibernate-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hibernate-dev

Re: [hibernate-dev] [NoORM] A simpler README.md?

[Guillaume Smet]

As mentioned on HipChat, feel free to do whatever you want for Search but I
want to keep the HV README.md as is.

So please do not make changes that impact the release process in this
regard (or make it conditional to Search).

Thanks.

On Mon, Jun 4, 2018 at 1:55 PM Yoann Rodiere  wrote:

> Hi everyone,
>
> TL;DR: I would like to strip down the README in Hibernate Search to
> redirect users to the website, which is better suited for presenting
> available versions, and helping users to get started. See what I mean in
> this
> PR . Any
> objections?
>
> Currently, the README.md in NoORM projects duplicates a bit of information
> from our website and documentation:
>
>- The version number and date of the latest release:
>https://github.com/hibernate/hibernate-search#hibernate-search vs.
>http://hibernate.org/search/releases/
>- A description of the project:
>https://github.com/hibernate/hibernate-search#description vs.
>http://hibernate.org/search/
>- The requirements:
>https://github.com/hibernate/hibernate-search#requirements vs.
>http://hibernate.org/search/releases/#compatibility-matrix or
>http://hibernate.org/search/releases/5.10/#compatibility
>- Installation instructions:
>https://github.com/hibernate/hibernate-search#maven +
>https://github.com/hibernate/hibernate-search#sourceforge-bundle vs.
>http://hibernate.org/search/releases/5.10/#get-it or
>http://hibernate.org/search/documentation/getting-started/
>
>
> Some of this information is updated manually when we don'r forget about it,
> and some of it (the latest release) is updated automatically when we
> perform a release on master.
>
> As a result, from time to time the information is not in sync. Right now,
> in Search, the version displayed in the README is 5.10.0.Final, whereas the
> latest release is 5.10.1.Final and the master branch hosts the
> 5.11.0-SNAPSHOT code. This is because the release scripts do not update
> master when we release from another branch, and we have to do it manually
> (that's expected: doing otherwise would be too complex).
>
> Also, the information is partial:
>
>- the README currently completely hides the fact that other Hibernate
>Search versions are still maintained and can work well with older
> versions
>of Hibernate ORM.
>- whenever the latest release is an alpha/beta/CR, we usually display
>installation instructions for the latest development version, and
>completely hide information about the latest stable version.
>
> What's worse, keeping the documentation on branch master the README on
> branch master may prove confusing: the README refers to the latest release,
> but the rest of the code may have been updated since the latest release,
> sometimes significantly so. We will have trouble dealing with this when we
> merge Hibernate Search 6, in particular.
>
> We may not agree on what is the best solution, but let's at least agree
> this is not ideal, especially when it comes to informing users about the
> stable version they want to use.
>
> We could put in more effort, try our very best to keep everything in sync
> and as complete as possible/necessary. Add more documentation about the
> release process. Try our best to do less mistakes. We could. But obviously,
> nobody is perfect, and so never will this README.
>
> Other projects, such as Spring Boot (
> https://github.com/spring-projects/spring-boot) or, more relevantly,
> Hibernate ORM (https://github.com/hwithibernate/hibernate-orm
> ), simply do not refer to the
> latest version in their README, and redirect to their website for all
> version-specific information. The README focuses on presenting the project,
> redirecting users to the website, and giving contributor-friendly
> information.
>
> I find this solution both elegant and powerful. Presenting the project is
> always necessary, but guiding users to the right version and giving getting
> started instructions is something complex, and something we already do on
> our website. So why not redirect people there? All links stay valid and
> relevant as long as the website is up and kept updated, and the impact of
> maintainers forgetting to update the README is far smaller. One less thing
> to worry about for maintainers, and better guidance for prospective users.
>
> A simple link to the getting started guide could be enough for most users,
> but we can go a step further and offer additional links. I just sent a pull
> request to show how I see it implemented in Search; please let me know what
> you think.
> The PR: https://github.com/hibernate/hibernate-search/pull/1692
> Preview of the README as seen from the GitHub web view:
>
> https://github.com/yrodiere/hibernate-search/blob/ae4d347fa4c647a3c5ddb6f43412cf3dce0e354e/README.md
>
> Cheers,
> --
> Yoann Rodiere
> yo...@hibernate.org / yrodi...@redhat.com
> Softw

Re: [hibernate-dev] [NoORM] A simpler README.md?

[Sanne Grinovero]

The historical objection has been that many users get the zip of our
project on a floppy disk and have no access to the internet.

That might be an obsolete statement nowadays? They'll use a
USB stick today ;)

Still, we know that e.g. people in China and similar places can't
always access our online resources, even if they "have internet".
University assignments/labs might have similar limitations even in Europe.

I have no strong objections, do it if you feel strongly about this
"inconsistency".

Personally, it hasn't bothered me much to occasionally have to update
the README, and I don't think people will expect that a zip they keep
in a drawer will be the better source of information if they happen to
have access to hibernate.org

Cheers,
Sanne



On 4 June 2018 at 12:51, Yoann Rodiere  wrote:
> Hi everyone,
>
> TL;DR: I would like to strip down the README in Hibernate Search to
> redirect users to the website, which is better suited for presenting
> available versions, and helping users to get started. See what I mean in this
> PR . Any
> objections?
>
> Currently, the README.md in NoORM projects duplicates a bit of information
> from our website and documentation:
>
>- The version number and date of the latest release:
>https://github.com/hibernate/hibernate-search#hibernate-search vs.
>http://hibernate.org/search/releases/
>- A description of the project:
>https://github.com/hibernate/hibernate-search#description vs.
>http://hibernate.org/search/
>- The requirements:
>https://github.com/hibernate/hibernate-search#requirements vs.
>http://hibernate.org/search/releases/#compatibility-matrix or
>http://hibernate.org/search/releases/5.10/#compatibility
>- Installation instructions:
>https://github.com/hibernate/hibernate-search#maven +
>https://github.com/hibernate/hibernate-search#sourceforge-bundle vs.
>http://hibernate.org/search/releases/5.10/#get-it or
>http://hibernate.org/search/documentation/getting-started/
>
>
> Some of this information is updated manually when we don'r forget about it,
> and some of it (the latest release) is updated automatically when we
> perform a release on master.
>
> As a result, from time to time the information is not in sync. Right now,
> in Search, the version displayed in the README is 5.10.0.Final, whereas the
> latest release is 5.10.1.Final and the master branch hosts the
> 5.11.0-SNAPSHOT code. This is because the release scripts do not update
> master when we release from another branch, and we have to do it manually
> (that's expected: doing otherwise would be too complex).
>
> Also, the information is partial:
>
>- the README currently completely hides the fact that other Hibernate
>Search versions are still maintained and can work well with older versions
>of Hibernate ORM.
>- whenever the latest release is an alpha/beta/CR, we usually display
>installation instructions for the latest development version, and
>completely hide information about the latest stable version.
>
> What's worse, keeping the documentation on branch master the README on
> branch master may prove confusing: the README refers to the latest release,
> but the rest of the code may have been updated since the latest release,
> sometimes significantly so. We will have trouble dealing with this when we
> merge Hibernate Search 6, in particular.
>
> We may not agree on what is the best solution, but let's at least agree
> this is not ideal, especially when it comes to informing users about the
> stable version they want to use.
>
> We could put in more effort, try our very best to keep everything in sync
> and as complete as possible/necessary. Add more documentation about the
> release process. Try our best to do less mistakes. We could. But obviously,
> nobody is perfect, and so never will this README.
>
> Other projects, such as Spring Boot (
> https://github.com/spring-projects/spring-boot) or, more relevantly,
> Hibernate ORM (https://github.com/hwithibernate/hibernate-orm
> ), simply do not refer to the
> latest version in their README, and redirect to their website for all
> version-specific information. The README focuses on presenting the project,
> redirecting users to the website, and giving contributor-friendly
> information.
>
> I find this solution both elegant and powerful. Presenting the project is
> always necessary, but guiding users to the right version and giving getting
> started instructions is something complex, and something we already do on
> our website. So why not redirect people there? All links stay valid and
> relevant as long as the website is up and kept updated, and the impact of
> maintainers forgetting to update the README is far smaller. One less thing
> to worry about for maintainers, and better guidance for prospective users.
>
> A simple link to the getting started guide 

Re: [hibernate-dev] [NoORM] A simpler README.md?

[Gunnar Morling]

No strong preference on my side, but I found this project of Lauri Apple
very useful:

https://github.com/LappleApple/feedmereadmes

You can ask for input on your README file there (they may send a PR for
updating it) and it also contains a "README maturity model". Perhaps it's
helpful for you, too.

--Gunnar


2018-06-04 14:32 GMT+02:00 Sanne Grinovero :

> The historical objection has been that many users get the zip of our
> project on a floppy disk and have no access to the internet.
>
> That might be an obsolete statement nowadays? They'll use a
> USB stick today ;)
>
> Still, we know that e.g. people in China and similar places can't
> always access our online resources, even if they "have internet".
> University assignments/labs might have similar limitations even in Europe.
>
> I have no strong objections, do it if you feel strongly about this
> "inconsistency".
>
> Personally, it hasn't bothered me much to occasionally have to update
> the README, and I don't think people will expect that a zip they keep
> in a drawer will be the better source of information if they happen to
> have access to hibernate.org
>
> Cheers,
> Sanne
>
>
>
> On 4 June 2018 at 12:51, Yoann Rodiere  wrote:
> > Hi everyone,
> >
> > TL;DR: I would like to strip down the README in Hibernate Search to
> > redirect users to the website, which is better suited for presenting
> > available versions, and helping users to get started. See what I mean in
> this
> > PR . Any
> > objections?
> >
> > Currently, the README.md in NoORM projects duplicates a bit of
> information
> > from our website and documentation:
> >
> >- The version number and date of the latest release:
> >https://github.com/hibernate/hibernate-search#hibernate-search vs.
> >http://hibernate.org/search/releases/
> >- A description of the project:
> >https://github.com/hibernate/hibernate-search#description vs.
> >http://hibernate.org/search/
> >- The requirements:
> >https://github.com/hibernate/hibernate-search#requirements vs.
> >http://hibernate.org/search/releases/#compatibility-matrix or
> >http://hibernate.org/search/releases/5.10/#compatibility
> >- Installation instructions:
> >https://github.com/hibernate/hibernate-search#maven +
> >https://github.com/hibernate/hibernate-search#sourceforge-bundle vs.
> >http://hibernate.org/search/releases/5.10/#get-it or
> >http://hibernate.org/search/documentation/getting-started/
> >
> >
> > Some of this information is updated manually when we don'r forget about
> it,
> > and some of it (the latest release) is updated automatically when we
> > perform a release on master.
> >
> > As a result, from time to time the information is not in sync. Right now,
> > in Search, the version displayed in the README is 5.10.0.Final, whereas
> the
> > latest release is 5.10.1.Final and the master branch hosts the
> > 5.11.0-SNAPSHOT code. This is because the release scripts do not update
> > master when we release from another branch, and we have to do it manually
> > (that's expected: doing otherwise would be too complex).
> >
> > Also, the information is partial:
> >
> >- the README currently completely hides the fact that other Hibernate
> >Search versions are still maintained and can work well with older
> versions
> >of Hibernate ORM.
> >- whenever the latest release is an alpha/beta/CR, we usually display
> >installation instructions for the latest development version, and
> >completely hide information about the latest stable version.
> >
> > What's worse, keeping the documentation on branch master the README on
> > branch master may prove confusing: the README refers to the latest
> release,
> > but the rest of the code may have been updated since the latest release,
> > sometimes significantly so. We will have trouble dealing with this when
> we
> > merge Hibernate Search 6, in particular.
> >
> > We may not agree on what is the best solution, but let's at least agree
> > this is not ideal, especially when it comes to informing users about the
> > stable version they want to use.
> >
> > We could put in more effort, try our very best to keep everything in sync
> > and as complete as possible/necessary. Add more documentation about the
> > release process. Try our best to do less mistakes. We could. But
> obviously,
> > nobody is perfect, and so never will this README.
> >
> > Other projects, such as Spring Boot (
> > https://github.com/spring-projects/spring-boot) or, more relevantly,
> > Hibernate ORM (https://github.com/hwithibernate/hibernate-orm
> > ), simply do not refer to
> the
> > latest version in their README, and redirect to their website for all
> > version-specific information. The README focuses on presenting the
> project,
> > redirecting users to the website, and giving contributor-friendly
> > information.
> >
> > I find thi

Re: [hibernate-dev] Breaking JBossStandAloneJtaPlatform backwards compatibility

[Sanne Grinovero]

On 4 June 2018 at 12:23, Tom Jenkinson  wrote:
>
>
> On 28 May 2018 at 12:23, Sanne Grinovero  wrote:
>>
>> On 28 May 2018 at 00:05, Steve Ebersole  wrote:
>> > JBossStandalone is meant for use of JBoss Transactions outside of
>> > WildFly.
>> > Why are we using it inside WildFly.  Inside WildFly, jipijapa ought to
>> > be
>> > defining that however it needs through a custom JtaPlatform and probably
>> > the
>> > JtaPlatformInitiator.
>>
>> I don't know the reasons, as I just started looking at WildFly Swarm
>> (now named Thorntail) and I'm merely reporting I see such exceptions.
>>
>> It's indeed surprising that this JTA Platform is being picked; I
>> chatted with Scott on another chat wondering why this system
>> apparently is not using JipiJapa - which would configure it correctly.
>> I guess it's not clear to me if Thorntail is to be considered "in" or
>> "outside" WildFly but I'm keeping this conversation for the Thorntail
>> team.
>>
>> All I observe is that 5.3.0.Final worked fine in Thorntail while
>> 5.3.1.Final will not work unless I figure out how to reconfigure it or
>> which other dependencies need switching - neither seems trivial and
>> that's unexpected from a micro update.
>> Same for the Narayana quickstarts and demo projects - maybe their
>> configuration could use some updates but I'm not sure, I'll leave that
>> to Tom and Gytis to decide.
>
>
> I just wanted to check, do we need any changes in the Narayana quickstart to
> deal with this? It reads as though since 5.3.2 we don't need to add a new
> dependency?
> https://github.com/jbosstm/quickstart/blob/master/jca-and-hibernate/src/test/resources/META-INF/persistence.xml#L39

Hi Tom,

I'm not sure either, let's test it after 5.3.2.Final is released -
likely we won't need to make any changes to the quickstarts.

@All:
For Hibernate Search, Thorntail, and Infinispan I already did the
upgrade and they come with custom JTA platform providers to dodge the
incompatibility.
The same trick wasn't possible with OGM as we test interactions with
the transaction system in many more subtle ways; I decided it wasn't
worth the effort of introducing all the scaffolding as we can just
wait for ORM 5.3.2 instead.

Thanks,
Sanne

>
>>
>>
>> Thanks,
>> Sanne
>>
>> >
>> >
>> > On Sun, May 27, 2018, 3:58 PM Sanne Grinovero 
>> > wrote:
>> >>
>> >> On 27 May 2018 at 15:29, Scott Marlow  wrote:
>> >> >
>> >> >
>> >> > On Sun, May 27, 2018 at 8:17 AM, Sanne Grinovero
>> >> > 
>> >> > wrote:
>> >> >>
>> >> >> On 27 May 2018 at 00:30, Scott Marlow  wrote:
>> >> >> > Next idea, we should first look for the WFTC classes, if not
>> >> >> > found,
>> >> >> > then
>> >> >> > look for Arjuna classes.
>> >> >>
>> >> >> +1 that would be nice and I see other implementations e.g.
>> >> >> JBossAppServerJtaPlatform have a precedent of attempting multiple
>> >> >> strategies to maintain backward compatibility.
>> >> >>
>> >> >> Created:
>> >> >>  - https://hibernate.atlassian.net/browse/HHH-12640
>> >> >
>> >> >
>> >> > https://github.com/hibernate/hibernate-orm/pull/2314
>> >> >
>> >> >>
>> >> >>
>> >> >>
>> >> >> Regarding the use of the old Arjuna name: you might be right that it
>> >> >> shouldn't be used, but it's still very common:
>> >> >>
>> >> >> even the Narayana quickstarts using Hibernate are broken by this
>> >> >> change, and so is any application running on WildFly Swarm or
>> >> >> Thorntail.
>> >> >>
>> >> >> I suppose something should be improved on their side as well, yet we
>> >> >> should give people time (by making it compatible like you suggested)
>> >> >> and help at least with some documented guidance - the fallback
>> >> >> strategy could log a warning to motivate people to update but IMO we
>> >> >> should start bugging people with such messages only when the other
>> >> >> runtimes and examples ship with the new defaults.
>> >> >>
>> >> >> Hibernate Search also has integration tests with Narayana
>> >> >> (standalone
>> >> >> JTA) and it's not clear to me now which dependencies I should be
>> >> >> changing; I suppose I'll figure it out soon as I need to release it
>> >> >> too :)
>> >> >>
>> >> >> The user experience after this error is quite bad: applications now
>> >> >> simply fail to start with a confusing
>> >> >> "javax.persistence.PersistenceException: No Persistence provider for
>> >> >> EntityManager named XYZ found", we give no better error and no clue
>> >> >> about needing to look into the used transactions implementation.
>> >> >>
>> >> >> Created:
>> >> >>  - https://hibernate.atlassian.net/browse/HHH-12639
>> >> >>
>> >> >> Thanks,
>> >> >> Sanne
>> >> >>
>> >> >>
>> >> >> >
>> >> >> > On Sat, May 26, 2018, 7:12 PM Scott Marlow 
>> >> >> > wrote:
>> >> >> >>
>> >> >> >>
>> >> >> >>
>> >> >> >> On Sat, May 26, 2018, 6:05 PM Scott Marlow 
>> >> >> >> wrote:
>> >> >> >>>
>> >> >> >>> Or, maybe we should just remove the JBOSS_TM_CLASS_NAME +
>> >> >> >>> JBOSS_UT_CLASS_NAME class references and instead JNDI lookup
>> >> >> >>> using
>

Re: [hibernate-dev] [NoORM] A simpler README.md?

[Yoann Rodiere]

> So please do not make changes that impact the release process in this
regard (or make it conditional to Search).

Sure.

> The historical objection has been that many users get the zip of our project
on a floppy disk and have no access to the internet.

Right, but in this case the information I'm removing is also present in the
reference documentation (near the top, at the beginning of the getting
started guide). Also, part of it is about downloading from Sourceforge
using Maven coordinates, so it doesn't seem like important information to
these people.

In the long run, I think the getting started guide from our website should
be merged with the one from our reference documentation. Then we would put
it somewhere it can be easily found, either directly in the reference
documentation, or in a separate folder next to the reference documentation
folder and the javadoc folder. We would then have an unambiguous place to
start from, addressing a specific version. And we would also potentially
have a clear, offline getting started guide that we could refer to from the
README.
But that's an orthogonal matter, I think.

> No strong preference on my side, but I found this project of Lauri Apple
very useful:

Thanks, this looks helpful indeed. Not sure I will follow all of their
recommendations, since their model seems to start from the premise that all
the documentation should be in the README (???), but it's definitely useful
to list everything that should be mentioned in some way.

On Mon, 4 Jun 2018 at 14:44 Gunnar Morling  wrote:

> No strong preference on my side, but I found this project of Lauri Apple
> very useful:
>
> https://github.com/LappleApple/feedmereadmes
>
> You can ask for input on your README file there (they may send a PR for
> updating it) and it also contains a "README maturity model". Perhaps it's
> helpful for you, too.
>
> --Gunnar
>
>
> 2018-06-04 14:32 GMT+02:00 Sanne Grinovero :
>
>> The historical objection has been that many users get the zip of our
>> project on a floppy disk and have no access to the internet.
>>
>> That might be an obsolete statement nowadays? They'll use a
>> USB stick today ;)
>>
>> Still, we know that e.g. people in China and similar places can't
>> always access our online resources, even if they "have internet".
>> University assignments/labs might have similar limitations even in Europe.
>>
>> I have no strong objections, do it if you feel strongly about this
>> "inconsistency".
>>
>> Personally, it hasn't bothered me much to occasionally have to update
>> the README, and I don't think people will expect that a zip they keep
>> in a drawer will be the better source of information if they happen to
>> have access to hibernate.org
>>
>> Cheers,
>> Sanne
>>
>>
>>
>> On 4 June 2018 at 12:51, Yoann Rodiere  wrote:
>> > Hi everyone,
>> >
>> > TL;DR: I would like to strip down the README in Hibernate Search to
>> > redirect users to the website, which is better suited for presenting
>> > available versions, and helping users to get started. See what I mean
>> in this
>> > PR . Any
>> > objections?
>> >
>> > Currently, the README.md in NoORM projects duplicates a bit of
>> information
>> > from our website and documentation:
>> >
>> >- The version number and date of the latest release:
>> >https://github.com/hibernate/hibernate-search#hibernate-search vs.
>> >http://hibernate.org/search/releases/
>> >- A description of the project:
>> >https://github.com/hibernate/hibernate-search#description vs.
>> >http://hibernate.org/search/
>> >- The requirements:
>> >https://github.com/hibernate/hibernate-search#requirements vs.
>> >http://hibernate.org/search/releases/#compatibility-matrix or
>> >http://hibernate.org/search/releases/5.10/#compatibility
>> >- Installation instructions:
>> >https://github.com/hibernate/hibernate-search#maven +
>> >https://github.com/hibernate/hibernate-search#sourceforge-bundle vs.
>> >http://hibernate.org/search/releases/5.10/#get-it or
>> >http://hibernate.org/search/documentation/getting-started/
>> >
>> >
>> > Some of this information is updated manually when we don'r forget about
>> it,
>> > and some of it (the latest release) is updated automatically when we
>> > perform a release on master.
>> >
>> > As a result, from time to time the information is not in sync. Right
>> now,
>> > in Search, the version displayed in the README is 5.10.0.Final, whereas
>> the
>> > latest release is 5.10.1.Final and the master branch hosts the
>> > 5.11.0-SNAPSHOT code. This is because the release scripts do not update
>> > master when we release from another branch, and we have to do it
>> manually
>> > (that's expected: doing otherwise would be too complex).
>> >
>> > Also, the information is partial:
>> >
>> >- the README currently completely hides the fact that other Hibernate
>> >Search versions are still maintained and can