From 621461fd1a51278c901399668c7d33a7474f4994 Mon Sep 17 00:00:00 2001 From: Cassandra Targett Date: Wed, 16 Oct 2019 11:03:17 -0500 Subject: [PATCH] SOLR-12786: Update Ref Guide build tool versions & fix section links for new format requirements --- dev-tools/scripts/jenkins.build.ref.guide.sh | 9 +++---- lucene/ivy-versions.properties | 7 ++--- solr/CHANGES.txt | 2 ++ .../asciidoctor-ant-1.6.0-alpha.5.jar.sha1 | 1 - solr/licenses/asciidoctor-ant-1.6.2.jar.sha1 | 1 + solr/solr-ref-guide/README.adoc | 26 +++++++++++-------- solr/solr-ref-guide/src/_config.yml.template | 4 +-- .../src/basic-authentication-plugin.adoc | 2 +- .../src/common-query-parameters.adoc | 2 +- solr/solr-ref-guide/src/enabling-ssl.adoc | 2 +- .../src/kerberos-authentication-plugin.adoc | 2 +- .../solr-ref-guide/src/metrics-reporting.adoc | 6 ++--- .../src/resource-and-plugin-loading.adoc | 2 +- ...ing-up-an-external-zookeeper-ensemble.adoc | 6 ++--- .../src/solr-control-script-reference.adoc | 4 +-- solr/solr-ref-guide/src/solr-tutorial.adoc | 2 +- .../src/solrcloud-autoscaling-api.adoc | 4 +-- .../src/solrcloud-autoscaling-triggers.adoc | 4 +-- ...okeeper-to-manage-configuration-files.adoc | 2 +- 19 files changed, 47 insertions(+), 41 deletions(-) delete mode 100644 solr/licenses/asciidoctor-ant-1.6.0-alpha.5.jar.sha1 create mode 100644 solr/licenses/asciidoctor-ant-1.6.2.jar.sha1 diff --git a/dev-tools/scripts/jenkins.build.ref.guide.sh b/dev-tools/scripts/jenkins.build.ref.guide.sh index f1a8bdb8c9d..e91c2401c19 100755 --- a/dev-tools/scripts/jenkins.build.ref.guide.sh +++ b/dev-tools/scripts/jenkins.build.ref.guide.sh @@ -60,11 +60,10 @@ echoRun "rvm $RUBY_VERSION@$GEMSET" # Activate this project's gemset # Install gems in the gemset. Param --force disables dependency conflict detection. echoRun "gem install --force --version 3.5.0 jekyll" -echoRun "gem uninstall --all --ignore-dependencies asciidoctor" # Get rid of all versions -echoRun "gem install --force --version 1.5.6.2 asciidoctor" -echoRun "gem install --force --version 2.1.0 jekyll-asciidoc" -echoRun "gem install --force --version 1.1.2 pygments.rb" -echoRun "gem install --force --version 3.0.9 slim" +echoRun "gem install --force --version 3.0.0 jekyll-asciidoc" +echoRun "gem install --force --version 4.0.1 slim" +echoRun "gem install --force --version 2.0.10 tilt" +echoRun "gem install --force --version 1.1.5 concurrent-ruby" cd solr/solr-ref-guide diff --git a/lucene/ivy-versions.properties b/lucene/ivy-versions.properties index 86cf9e2afe7..4d3b6c0caac 100644 --- a/lucene/ivy-versions.properties +++ b/lucene/ivy-versions.properties @@ -223,9 +223,10 @@ org.apache.zookeeper.version = 3.5.5 /org.apache.zookeeper/zookeeper = ${org.apache.zookeeper.version} /org.apache.zookeeper/zookeeper-jute = ${org.apache.zookeeper.version} -# v1.6.0-alpha.5 of asciidoctor-ant includes asciidoctorj-pdf 1.5.0-alpha.16, -# which is the same as asciidoctor-pdf 1.5.0-alpha.16 -/org.asciidoctor/asciidoctor-ant = 1.6.0-alpha.5 +# v1.6.2 of asciidoctor-ant includes asciidoctorj 1.6.2, which uses +# asciidoctor 1.5.8, and asciidoctorj-pdf 1.5.0-alpha.16, which is the same +# as asciidoctor-pdf 1.5.0-alpha.16 +/org.asciidoctor/asciidoctor-ant = 1.6.2 /org.aspectj/aspectjrt = 1.8.0 diff --git a/solr/CHANGES.txt b/solr/CHANGES.txt index f1571b13106..a78a4725442 100644 --- a/solr/CHANGES.txt +++ b/solr/CHANGES.txt @@ -364,6 +364,8 @@ Other Changes * SOLR-13787: An annotation based system to write v2 APIs (noble) +* SOLR-12786: Update Ref Guide build tool versions (Cassandra) + ================== 8.2.0 ================== Consult the LUCENE_CHANGES.txt file for additional, low level, changes in this release. diff --git a/solr/licenses/asciidoctor-ant-1.6.0-alpha.5.jar.sha1 b/solr/licenses/asciidoctor-ant-1.6.0-alpha.5.jar.sha1 deleted file mode 100644 index 0da9ca2b120..00000000000 --- a/solr/licenses/asciidoctor-ant-1.6.0-alpha.5.jar.sha1 +++ /dev/null @@ -1 +0,0 @@ -741c5e5afd8a2c7d415feb7b9a8d6fe8a6cca57c diff --git a/solr/licenses/asciidoctor-ant-1.6.2.jar.sha1 b/solr/licenses/asciidoctor-ant-1.6.2.jar.sha1 new file mode 100644 index 00000000000..558a01f5839 --- /dev/null +++ b/solr/licenses/asciidoctor-ant-1.6.2.jar.sha1 @@ -0,0 +1 @@ +c5ba599e3918e7a3316e6bf110cadd5aeb2a026b diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc index d485b996228..61afa4f4d40 100644 --- a/solr/solr-ref-guide/README.adoc +++ b/solr/solr-ref-guide/README.adoc @@ -23,17 +23,21 @@ Raw content is stored in Asciidoc (`.adoc`) formatted files in the `src/` direct == Prerequisites for Building These files are processed with AsciiDoctor in 2 different ways: -* Via Jekyll to build an HTML browsable version of the Ref Guide. -** Prerequisites: `Ruby` (v2.1 or higher) and the following gems must be installed: -*** `jekyll`: v3.5, not v4.x. Use `gem install jekyll --force --version 3.5.0` to force install of Jekyll 3.5.0. -*** `asciidoctor`: v1.5.6.2, not 1.5.7 or higher. Use `gem install asciidoctor --force --version 1.5.6.2`. NOTE: You must do this before installing `jekyll-asciidoc` or you'll get a version of Asciidoctor that we can't use yet. -*** `jekyll-asciidoc`: v2.1 or higher. Use `gem install jekyll-asciidoc` to install. -*** `pygments.rb`: v1.1.2 or higher. Use `gem install pygments.rb` to install. -// The following is only necessary until we are on Asciidoctor 1.5.8 or higher. -// See https://github.com/asciidoctor/asciidoctor/issues/2928 for details of the problem with Slim 4.x and higher. -*** `slim`: v3.0.1 or higher, only to 3.0.9. Do *NOT* use Slim 4.x. Use `gem install slim --force --version 3.0.9` to install. -* Via `asciidoctor-ant` to build the officially released PDF version of the Ref Guide. -** Prerequisites: None beyond those required to use the main Lucene/Solr build: Java, and Ant. +* HTML version, using Jekyll: +** `Ruby` (v2.3 or higher) +** The following gems must be installed: +*** `jekyll`: v3.5, not v4.x. +Use `gem install jekyll --force --version 3.5.0` to force install of v3.5.0. +*** `jekyll-asciidoc`: v2.1 or higher; latest version (3.0.0) is fine. +Use `gem install jekyll-asciidoc` to install. +*** `slim`: v3.0 or higher; latest version (4.0.1) is fine. +Use `gem install slim` to install. +*** `tilt`: v1.0 or higher; latest version (2.0.10) is fine. +Use `gem install tilt` to install. +*** `concurrent-ruby`: v1.0 or higher; latest version (1.1.5) is fine. +Use `gem install concurrent-ruby` to install. +* PDF version, via `asciidoctor-ant`: +** None beyond those required to use the main Lucene/Solr build: Java, and Ant. == Building the Guide For details on building the ref guide, see `ant -p`. diff --git a/solr/solr-ref-guide/src/_config.yml.template b/solr/solr-ref-guide/src/_config.yml.template index 7c29200fdeb..5fc023a6064 100755 --- a/solr/solr-ref-guide/src/_config.yml.template +++ b/solr/solr-ref-guide/src/_config.yml.template @@ -94,7 +94,7 @@ asciidoctor: <<: *solr-attributes-ref attribute-missing: "warn" icons: "font" - source-highlighter: "pygments" - pygments-css: "style" + source-highlighter: "rouge" + rouge-theme: "thankful-eyes" # NOTE: do *NOT* use an self-empty div tag (ie:
) here - it will break jquery section-toc: "
" diff --git a/solr/solr-ref-guide/src/basic-authentication-plugin.adoc b/solr/solr-ref-guide/src/basic-authentication-plugin.adoc index 18ad2b8f221..1bf61928637 100644 --- a/solr/solr-ref-guide/src/basic-authentication-plugin.adoc +++ b/solr/solr-ref-guide/src/basic-authentication-plugin.adoc @@ -71,7 +71,7 @@ If you are using SolrCloud, you must upload `security.json` to ZooKeeper. You ca bin/solr zk cp file:path_to_local_security.json zk:/security.json -z localhost:9983 ---- -NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from the above command. +NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from the above command. === Caveats diff --git a/solr/solr-ref-guide/src/common-query-parameters.adoc b/solr/solr-ref-guide/src/common-query-parameters.adoc index aeb77df3c01..0486ff1a41a 100644 --- a/solr/solr-ref-guide/src/common-query-parameters.adoc +++ b/solr/solr-ref-guide/src/common-query-parameters.adoc @@ -102,7 +102,7 @@ fq=+popularity:[10 TO *] +section:0 ---- * The document sets from each filter query are cached independently. Thus, concerning the previous examples: use a single `fq` containing two mandatory clauses if those clauses appear together often, and use two separate `fq` parameters if they are relatively independent. (To learn about tuning cache sizes and making sure a filter cache actually exists, see <>.) -* It is also possible to use <> inside the `fq` to cache clauses individually and - among other things - to achieve union of cached filter queries. +* It is also possible to use <> inside the `fq` to cache clauses individually and - among other things - to achieve union of cached filter queries. * As with all parameters: special characters in an URL need to be properly escaped and encoded as hex values. Online tools are available to help you with URL-encoding. For example: http://meyerweb.com/eric/tools/dencoder/. diff --git a/solr/solr-ref-guide/src/enabling-ssl.adoc b/solr/solr-ref-guide/src/enabling-ssl.adoc index 2d9e69c4609..93cf2ea9c2b 100644 --- a/solr/solr-ref-guide/src/enabling-ssl.adoc +++ b/solr/solr-ref-guide/src/enabling-ssl.adoc @@ -247,7 +247,7 @@ If you have set up your ZooKeeper cluster to use a <>) you can omit `-z ` from all of the `bin/solr`/`bin\solr.cmd` commands below. +NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from all of the `bin/solr`/`bin\solr.cmd` commands below. ==== Create Solr Home Directories for Two Nodes diff --git a/solr/solr-ref-guide/src/kerberos-authentication-plugin.adoc b/solr/solr-ref-guide/src/kerberos-authentication-plugin.adoc index ed0b3cb900a..90682be06eb 100644 --- a/solr/solr-ref-guide/src/kerberos-authentication-plugin.adoc +++ b/solr/solr-ref-guide/src/kerberos-authentication-plugin.adoc @@ -298,7 +298,7 @@ Once the configuration is complete, you can start Solr with the `bin/solr` scrip bin/solr -c -z server1:2181,server2:2181,server3:2181/solr ---- -NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from the above command. +NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from the above command. === Test the Configuration diff --git a/solr/solr-ref-guide/src/metrics-reporting.adoc b/solr/solr-ref-guide/src/metrics-reporting.adoc index dafa172bcdb..ecefda77c11 100644 --- a/solr/solr-ref-guide/src/metrics-reporting.adoc +++ b/solr/solr-ref-guide/src/metrics-reporting.adoc @@ -87,7 +87,7 @@ The metrics available in your system can be customized by modifying the `> for more information about the `solr.xml` file, where to find it, and how to edit it. -=== The Element +=== The Element This section of `solr.xml` allows you to define the system properties which are considered system-sensitive and should not be exposed via the Metrics API. @@ -106,11 +106,11 @@ If this section is not defined, the following default configuration is used whic ---- -=== The Element +=== The Element Reporters consume the metrics data generated by Solr. See the section <> below for more details on how to configure custom reporters. -=== The Element +=== The Element Suppliers help Solr generate metrics data. The `` section of `solr.xml` allows you to define your own implementations of metrics and configure parameters for them. diff --git a/solr/solr-ref-guide/src/resource-and-plugin-loading.adoc b/solr/solr-ref-guide/src/resource-and-plugin-loading.adoc index 04dc84078df..6efd1353290 100644 --- a/solr/solr-ref-guide/src/resource-and-plugin-loading.adoc +++ b/solr/solr-ref-guide/src/resource-and-plugin-loading.adoc @@ -46,7 +46,7 @@ CAUTION: By default, ZooKeeper's file size limit is 1MB. If your files are large Under standalone Solr, when looking up a plugin or resource to be loaded, Solr's resource loader will first look under the `/conf/` directory. If the plugin or resource is not found, the configured plugin and resource file paths are searched - see the section <> below. -On core load, Solr's resource loader constructs a list of paths (subdirectories and jars), first under <>, and then under directories pointed to by <` directives in SolrConfig>>. +On core load, Solr's resource loader constructs a list of paths (subdirectories and jars), first under <>, and then under directories pointed to by <` directives in SolrConfig>>. When looking up a resource or plugin to be loaded, the paths on the list are searched in the order they were added. diff --git a/solr/solr-ref-guide/src/setting-up-an-external-zookeeper-ensemble.adoc b/solr/solr-ref-guide/src/setting-up-an-external-zookeeper-ensemble.adoc index 224dd00dd5e..837c4d9f79d 100644 --- a/solr/solr-ref-guide/src/setting-up-an-external-zookeeper-ensemble.adoc +++ b/solr/solr-ref-guide/src/setting-up-an-external-zookeeper-ensemble.adoc @@ -201,7 +201,7 @@ And create the `myid` file in the `/var/lib/zookeeper` directory: Repeat this for servers 4 and 5 if you are creating a 5-node ensemble (a rare case). -=== ZooKeeper Environment Configuration +=== ZooKeeper Environment Configuration To ease troubleshooting in case of problems with the ensemble later, it's recommended to run ZooKeeper with logging enabled and with proper JVM garbage collection (GC) settings. @@ -295,9 +295,9 @@ For example, to point the Solr instance to the ZooKeeper you've started on port bin/solr start -e cloud -z zk1:2181,zk2:2181,zk3:2181/solr ---- -=== Updating Solr's Include Files +=== Updating Solr Include Files -If you update Solr's include file (`solr.in.sh` or `solr.in.cmd`), which overrides defaults used with `bin/solr`, you will not have to use the `-z` parameter with `bin/solr` commands. +If you update Solr include files (`solr.in.sh` or `solr.in.cmd`), which overrides defaults used with `bin/solr`, you will not have to use the `-z` parameter with `bin/solr` commands. [.dynamic-tabs] diff --git a/solr/solr-ref-guide/src/solr-control-script-reference.adoc b/solr/solr-ref-guide/src/solr-control-script-reference.adoc index 8f436b5011b..05f94ac06ea 100644 --- a/solr/solr-ref-guide/src/solr-control-script-reference.adoc +++ b/solr/solr-ref-guide/src/solr-control-script-reference.adoc @@ -60,7 +60,7 @@ Start Solr in SolrCloud mode, which will also launch the embedded ZooKeeper inst + This option can be shortened to simply `-c`. + -If you are already running a ZooKeeper ensemble that you want to use instead of the embedded (single-node) ZooKeeper, you should also either specify `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) or pass the -z parameter. +If you are already running a ZooKeeper ensemble that you want to use instead of the embedded (single-node) ZooKeeper, you should also either specify `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) or pass the -z parameter. + For more details, see the section <> below. + @@ -172,7 +172,7 @@ The `-c` and `-cloud` options are equivalent: If you specify a ZooKeeper connection string, such as `-z 192.168.1.4:2181`, then Solr will connect to ZooKeeper and join the cluster. -NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from all `bin/solr` commands. +NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from all `bin/solr` commands. When starting Solr in SolrCloud mode, if you do not define `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` nor specify the `-z` option, then Solr will launch an embedded ZooKeeper server listening on the Solr port + 1000, i.e., if Solr is running on port 8983, then the embedded ZooKeeper will be listening on port 9983. diff --git a/solr/solr-ref-guide/src/solr-tutorial.adoc b/solr/solr-ref-guide/src/solr-tutorial.adoc index ca881341e70..77b0deb1c9c 100644 --- a/solr/solr-ref-guide/src/solr-tutorial.adoc +++ b/solr/solr-ref-guide/src/solr-tutorial.adoc @@ -513,7 +513,7 @@ This starts the first node. When it's done start the second node, and tell it ho `./bin/solr start -c -p 7574 -s example/cloud/node2/solr -z localhost:9983` -NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from the above command. +NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from the above command. === Create a New Collection diff --git a/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc b/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc index 24da7594991..0ae519c56eb 100644 --- a/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc +++ b/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc @@ -676,7 +676,7 @@ The `remove-policy` command accepts a policy name to be removed from Solr. The p If you attempt to remove a policy that is being used by a collection, this command will fail to delete the policy until the collection itself is deleted. -=== Create/Update Trigger +=== Create or Update a Trigger The `set-trigger` command can be used to create a new trigger or overwrite an existing one. @@ -732,7 +732,7 @@ The `remove-trigger` command can be used to remove a trigger. It accepts a singl } ---- -=== Create/Update Trigger Listener +=== Create or Update a Trigger Listener The `set-listener` command can be used to create or modify a listener for a trigger. diff --git a/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc b/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc index bf0953e9112..de346d846b4 100644 --- a/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc +++ b/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc @@ -55,7 +55,7 @@ generated, which may significantly differ due to the rate limits set by `waitFor indicates the nodes that were lost or added. == Trigger Configuration -Trigger configurations are managed using the <> with the commands `<>`, `<>`, +Trigger configurations are managed using the <> with the commands `<>`, `<>`, `suspend-trigger`, and `resume-trigger`. === Trigger Properties @@ -606,4 +606,4 @@ old markers for such events so that they don't accumulate over time. This trigge === `solr.ExecutePlanAction` This action simply executes any collection admin requests generated by other actions - in particular, in the default configuration it executes `DELETESHARD` requests produced by -`solr.InactiveShardPlanAction`, as described above. \ No newline at end of file +`solr.InactiveShardPlanAction`, as described above. diff --git a/solr/solr-ref-guide/src/using-zookeeper-to-manage-configuration-files.adoc b/solr/solr-ref-guide/src/using-zookeeper-to-manage-configuration-files.adoc index 546ee99b197..fe13460a5f0 100644 --- a/solr/solr-ref-guide/src/using-zookeeper-to-manage-configuration-files.adoc +++ b/solr/solr-ref-guide/src/using-zookeeper-to-manage-configuration-files.adoc @@ -93,4 +93,4 @@ If you for example would like to keep your `solr.xml` in ZooKeeper to avoid havi bin/solr zk cp file:local/file/path/to/solr.xml zk:/solr.xml -z localhost:2181 ---- -NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from the above command. +NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <>) you can omit `-z ` from the above command.