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