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)

2021-10-26 21:20:42 +02:00 · 2021-10-26 21:20:42 +02:00 · 08c0356664
parent 780846a732
commit 08c0356664
4 changed files with 40 additions and 53 deletions
--- 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.

--- 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.
-
--- 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'
--- a/lucene/distribution/src/binary-release/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: