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 yo...@hibernate.org / yrodi...@redhat.com Software Engineer Hibernate NoORM team _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev