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

regard (or make it conditional to Search). Sure. on a floppy disk and have no access to the internet. Right, but in this case the information I'm removing is also present in the reference documentation (near the top, at the beginning of the getting started guide). Also, part of it is about downloading from Sourceforge using Maven coordinates, so it doesn't seem like important information to these people. In the long run, I think the getting started guide from our website should be merged with the one from our reference documentation. Then we would put it somewhere it can be easily found, either directly in the reference documentation, or in a separate folder next to the reference documentation folder and the javadoc folder. We would then have an unambiguous place to start from, addressing a specific version. And we would also potentially have a clear, offline getting started guide that we could refer to from the README. But that's an orthogonal matter, I think. very useful: Thanks, this looks helpful indeed. Not sure I will follow all of their recommendations, since their model seems to start from the premise that all the documentation should be in the README (???), but it's definitely useful to list everything that should be mentioned in some way. On Mon, 4 Jun 2018 at 14:44 Gunnar Morling <gunnar(a)hibernate.org&gt; wrote: > 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(a)hibernate.org&gt;: > >> 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/ae4d347fa4c647a3c5ddb6f... >> > >> > 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 >> > > -- Yoann Rodiere yoann(a)hibernate.org / yrodiere(a)redhat.com Software Engineer Hibernate NoORM team