[lucene] branch main updated: LUCENE-10163: clean up and remove some old cruft in readme files. Move binary release only README.md to the distribution project so that it doesn't look weird in the source tree. (#406)

[dw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

dweiss pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/lucene.git


The following commit(s) were added to refs/heads/main by this push:
     new 08c0356  LUCENE-10163: clean up and remove some old cruft in readme files. Move binary release only README.md to the distribution project so that it doesn't look weird in the source tree. (#406)
08c0356 is described below

commit 08c03566648c0b024b8160869b3d694c3cebaabd
Author: Dawid Weiss <da...@carrotsearch.com>
AuthorDate: Tue Oct 26 21:20:42 2021 +0200

    LUCENE-10163: clean up and remove some old cruft in readme files. Move binary release only README.md to the distribution project so that it doesn't look weird in the source tree. (#406)
---
 README.md                                          | 34 ++++++++++---------
 lucene/JRE_VERSION_MIGRATION.md                    | 38 ++++++++--------------
 lucene/distribution/binary-release.gradle          | 15 ++++-----
 .../src/binary-release}/README.md                  |  6 ++--
 4 files changed, 40 insertions(+), 53 deletions(-)

diff --git a/README.md b/README.md
index 74ccf69..f6c3619 100644
--- a/README.md
+++ b/README.md
@@ -38,8 +38,8 @@ comprehensive documentation, visit:
 
 ### Basic steps:
   
-  0. Install OpenJDK 11 (or greater up until version 15)
-  1. Download Lucene from Apache and unpack it (or clone the git repository).
+  0. Install OpenJDK 11 (or greater).
+  1. Clone Lucene's git repository (or download the source distribution).
   2. Run gradle launcher script (`gradlew`).
 
 ### Step 0) Set up your development environment (OpenJDK 11 or greater)
@@ -51,10 +51,10 @@ Java 11 or later.
 
 Lucene uses [Gradle](https://gradle.org/) for build control. Gradle is itself Java-based
 and may be incompatible with newer Java versions; you can still build and test 
-Lucene with these Java releases, see help/tests.txt for more information.
+Lucene with these Java releases, see [jvms.txt](./help/jvms.txt) for more information.
 
-NOTE: Lucene changed from Ant to Gradle as of release 9.0. Prior releases
-still use Ant.
+NOTE: Lucene changed from Apache Ant to Gradle as of release 9.0. Prior releases
+still use Apache Ant.
 
 ### Step 1) Checkout/Download Lucene source code
 
@@ -66,8 +66,7 @@ or get Lucene source archives for a particular release from:
 
   https://lucene.apache.org/core/downloads.html
 
-Download either a zip or a tarred/gzipped version of the archive, and
-uncompress it into a directory of your choice.
+Download the source archive and uncompress it into a directory of your choice.
 
 ### Step 2) Run Gradle
 
@@ -80,28 +79,31 @@ If you want to build Lucene, type:
 ./gradlew assemble
 ```
 
-NOTE: DO NOT use `gradle` command that is already installed on your machine (unless you know what you'll do).
-The "gradle wrapper" (gradlew) does the job - downloads the correct version of it, setups necessary configurations.
+NOTE: DO NOT use the `gradle` command that is perhaps installed on your machine. This may
+result in using a different gradle version than the project requires and this is known
+to lead to very cryptic errors. The "gradle wrapper" (gradlew script) does everything
+required to build the project from scratch: it downloads the correct version of gradle,
+sets up sane local configurations and is tested on multiple environments.
 
-The first time you run Gradle, it will create a file "gradle.properties" that
+The first time you run gradlew, it will create a file "gradle.properties" that
 contains machine-specific settings. Normally you can use this file as-is, but it
 can be modified if necessary.
 
 `./gradlew check` will assemble Lucene and run all validation
-  tasks (including unit tests).
+  tasks (including tests).
 
-`./gradlew help` will print a list of help guides that help understand how
-  the build and typical workflow works.
+`./gradlew help` will print a list of help guides that introduce and explain
+  various parts of the build system, including typical workflow tasks.
 
-If you want to build the documentation, type:
+If you want to just build the documentation, type:
 
 ```
 ./gradlew documentation
 ```
 
-### Gradle build and IDE support
+### IDE support
 
-- *IntelliJ* - IntelliJ idea can import the project out of the box.
+- *IntelliJ* - IntelliJ idea can import and build gradle-based projects out of the box.
 - *Eclipse*  - Basic support ([help/IDEs.txt](https://github.com/apache/lucene/blob/main/help/IDEs.txt#L7)).
 - *Netbeans* - Not tested.
 
diff --git a/lucene/JRE_VERSION_MIGRATION.md b/lucene/JRE_VERSION_MIGRATION.md
index 90196d2..859b75f 100644
--- a/lucene/JRE_VERSION_MIGRATION.md
+++ b/lucene/JRE_VERSION_MIGRATION.md
@@ -20,37 +20,25 @@
 If possible, use the same JRE major version at both index and search time.
 When upgrading to a different JRE major version, consider re-indexing. 
 
-Different JRE major versions may implement different versions of Unicode,
+Different Java versions may implement different versions of Unicode,
 which will change the way some parts of Lucene treat your text.
 
-For example: with Java 1.4, `LetterTokenizer` will split around the character U+02C6,
-but with Java 5 it will not.
-This is because Java 1.4 implements Unicode 3, but Java 5 implements Unicode 4.
+An (outdated) example: with Java 1.4, `LetterTokenizer` will split around the 
+character U+02C6, but with Java 5 it will not. This is because Java 1.4 
+implements Unicode 3, but Java 5 implements Unicode 4.
 
-For reference, JRE major versions with their corresponding Unicode versions:
+The version of Unicode supported by Java is listed in the documentation
+of java.lang.Character class. For reference, Java versions after Java 11
+support the following Unicode versions:
 
- * Java 1.4, Unicode 3.0
- * Java 5, Unicode 4.0
- * Java 6, Unicode 4.0
- * Java 7, Unicode 6.0
- * Java 8, Unicode 6.2
- * Java 9, Unicode 8.0
+ * Java 11, Unicode 10.0
+ * Java 12, Unicode 11.0
+ * Java 13, Unicode 12.1
+ * Java 15, Unicode 13.0
+ * Java 16, Unicode 13.0
+ * Java 17, Unicode 13.0
 
 In general, whether you need to re-index largely depends upon the data that
 you are searching, and what was changed in any given Unicode version. For example, 
 if you are completely sure your content is limited to the "Basic Latin" range
 of Unicode, you can safely ignore this. 
-
-## Special Notes: LUCENE 2.9 TO 3.0, JAVA 1.4 TO JAVA 5 TRANSITION
-
-* `StandardAnalyzer` will return the same results under Java 5 as it did under 
-Java 1.4. This is because it is largely independent of the runtime JRE for
-Unicode support, (except for lowercasing).  However, no changes to
-casing have occurred in Unicode 4.0 that affect StandardAnalyzer, so if you are 
-using this Analyzer you are NOT affected.
-
-* `SimpleAnalyzer`, `StopAnalyzer`, `LetterTokenizer`, `LowerCaseFilter`, and 
-`LowerCaseTokenizer` may return different results, along with many other `Analyzer`s
-and `TokenStream`s in Lucene's analysis modules. If you are using one of these 
-components, you may be affected.
-
diff --git a/lucene/distribution/binary-release.gradle b/lucene/distribution/binary-release.gradle
index 20e5f0b..634f582 100644
--- a/lucene/distribution/binary-release.gradle
+++ b/lucene/distribution/binary-release.gradle
@@ -60,29 +60,26 @@ configure(project(":lucene:distribution")) {
       copy.setMode(0755)
     }
 
-    // Cherry-picked root-level files.
+    // Attach binary release exclusive files.
+    from(file("src/binary-release"), {
+    })
+
+    // Cherry-pick certain files from the root.
     from(project(':').projectDir, {
         include "LICENSE.txt"
         include "NOTICE.txt"
     })
 
-    // Cherry-picked lucene-level files.
+    // Cherry-pick certain files from the lucene module.
     from(project(':lucene').projectDir, {
       include "CHANGES.txt"
       include "JRE_VERSION_MIGRATION.md"
       include "MIGRATE.md"
-      include "README.md"
       include "SYSTEM_REQUIREMENTS.md"
 
       include "licenses/*"
     })
 
-    // Analysis container is not a submodule but include its readme file.
-    from(project(':lucene:analysis').projectDir) {
-      include "README.txt"
-      into 'analysis'
-    }
-
     // The documentation.
     from(configurations.docs, {
       into 'docs'
diff --git a/lucene/README.md b/lucene/distribution/src/binary-release/README.md
similarity index 84%
rename from lucene/README.md
rename to lucene/distribution/src/binary-release/README.md
index 76f8a31..f4efffc 100644
--- a/lucene/README.md
+++ b/lucene/distribution/src/binary-release/README.md
@@ -19,9 +19,9 @@
 
 ## Introduction
 
-Lucene is a Java full-text search engine.  Lucene is not a complete
-application, but rather a code library and API that can easily be used
-to add search capabilities to applications.
+This is a binary distribution of Lucene. Lucene is a Java full-text 
+search engine. Lucene is not a complete application, but rather a code library 
+and an API that can easily be used to add search capabilities to applications.
 
  * The Lucene web site is at: https://lucene.apache.org/
  * Please join the Lucene-User mailing list by sending a message to: