[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 <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