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

Mon Jun 4 08:44:12 EDT 2018

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 <sanne at hibernate.org>:

> 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
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>