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

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(a)hibernate.org&gt; 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(a)hibernate.org / yrodiere(a)redhat.com > Software Engineer > Hibernate NoORM team > _______________________________________________ > hibernate-dev mailing list > hibernate-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev