[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 <yoann at hibernate.org> 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 <https://github.com/hibernate/hibernate-search/pull/1692>. 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
> <https://github.com/hibernate/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
> yoann at hibernate.org / yrodiere at redhat.com
> Software Engineer
> Hibernate NoORM team
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>