Apache Solr open-source search software
SOLR-12930: Simplify and Organize Developer Docs (#69)
Eric Pugh04ad0955e70d
diff --git a/dev-docs/FAQ.adoc b/dev-docs/FAQ.adocnew file mode 100644index 00000000000..1ea1aa1a588--- /dev/null+++ b/dev-docs/FAQ.adoc@@ -0,0 +1,11 @@+= Frequently Asked Questions+:toc: left+++== FAQ++This document provides a quick reference for frequently questioned concepts and features in Credentials.++=== What do I do with NOTICE.txt if I don't have one to satisfy Gradle?++You create an empty file, similar to the `/solr/licenses/antlr4-runtime-NOTICE.txt`diff --git a/dev-docs/README.adoc b/dev-docs/README.adocindex bdb7410dc48..bb0d17d75f9 100644--- a/dev-docs/README.adoc+++ b/dev-docs/README.adoc@@ -1,4 +1,4 @@-= Lucene Project Docs+= Solr Developer Docs// Licensed to the Apache Software Foundation (ASF) under one// or more contributor license agreements. See the NOTICE file// distributed with this work for additional information@@ -16,6 +16,16 @@// specific language governing permissions and limitations// under the License.-This directory includes information for the Lucene project overall.+This directory includes information for Solr developers. There are some other+sources of information for learning about developing on Solr:-Also look in `lucene/dev-docs` for Lucene developer information and `solr/dev-docs` for Solr developer information.+1. The help .txt files for the Gradle commands in the `help/` directory.++2. Information on how to handle adding dependencies and related licensing+details, see the information in `/solr/licenses/README.committers.txt`.++3. The Solr Reference Guide, which provides primarily end user oriented documentation.+However, the Ref Guide hosts it's own documentation on how to write Ref Guide content.++There are a number of tools related to doing development on Solr available in the `/dev-tools`+directory.diff --git a/dev-docs/dev-utilities.adoc b/dev-docs/cloud-script.adocsimilarity index 53%rename from dev-docs/dev-utilities.adocrename to dev-docs/cloud-script.adocindex fb85a25276c..3ff9c7f0cb3 100644--- a/dev-docs/dev-utilities.adoc+++ b/dev-docs/cloud-script.adoc@@ -1,23 +1,24 @@-= Developer Utilities+= Cloud Script:toc: left-// This is probably going to get split soon, but for the moment, since we only have one dev-docs directory...-== Lucene-TODO: add something here :)== Solr-=== Cluster on localhost+=== Running a local SolrCloud Cluster-At times, it is important to do manual testing on a running server, and in many cases it is a good idea to test in a clustered environment to ensure that features play nice both locally and across nodes. To lower the barrier for realistic local testing, there is a script at `solr/cloud-dev/cloud.sh`. Typical usage of the script is:+At times, it is important to do manual testing on a running server, and in many+cases it is a good idea to test in a clustered environment to ensure that features+play nice both locally and across nodes. To lower the barrier for realistic local+testing, there is a script at `dev-tools/scripts/cloud.sh`.NOTE: This script only supports POSIX environments. There is no similar .bat script at this time.-1. Copy the script to a location outside the lucene-solr working copy. Trying to use it from within the working copy will leave you fighting version control to avoid checking in files.+Typical usage of the script is:++1. Copy the script to a location outside the `./solr/` working copy such as `<GIT_CHECKOUT>/../solr-testing`. Trying to use it from within the working copy will leave you fighting version control to avoid checking in files.2. Edit the script to provide a proper back reference to your working copy for `DEFAULT_VCS_WORKSPACE` (the default is `../code/lucene-solr`)-3. Chmod cloud.sh to make it executable-4. Start a local zookeeper instance. This zookeeper must be running on localhost, but the port can be adjusted with a `-z` option passed to the script.-5. run ./cloud.sh new -r+3. Start a local zookeeper instance. This zookeeper must be running on localhost, but the port can be adjusted with a `-z` option passed to the script. `docker run -p 2181:2181 zookeeper` is one option to start up a local Zookeeper.+4. run ./cloud.sh new -rThe command in the final step will:@@ -27,4 +28,5 @@ The command in the final step will:4. Start solr on ports 8981, 8982, 8983 and 8984 with listening debugger ports on 5001, 5002, 5003, and 5004.5. Each solr instance will place its data and solr.log in a corresponding directory such as `./2021-02-21/n1`, `./2021-02-21/n2` etc.-The script supports `start`, `stop` and `restart` commands, and a variety of options detailed in the extensive introductory comment in cloud.sh. You should expect that comment to contain the latest information and if it contradicts this document it likely is more correct.\ No newline at end of file+The script supports `start`, `stop` and `restart` commands, and a variety of options+detailed in the extensive introductory comment in cloud.sh.diff --git a/solr/dev-docs/overseer/images/configSet-processor-flow.png b/dev-docs/overseer/images/configSet-processor-flow.pngsimilarity index 100%rename from solr/dev-docs/overseer/images/configSet-processor-flow.pngrename to dev-docs/overseer/images/configSet-processor-flow.pngdiff --git a/solr/dev-docs/overseer/images/locking-levels.png b/dev-docs/overseer/images/locking-levels.pngsimilarity index 100%rename from solr/dev-docs/overseer/images/locking-levels.pngrename to dev-docs/overseer/images/locking-levels.pngdiff --git a/solr/dev-docs/overseer/images/session-lockTree-20nodes.png b/dev-docs/overseer/images/session-lockTree-20nodes.pngsimilarity index 100%rename from solr/dev-docs/overseer/images/session-lockTree-20nodes.pngrename to dev-docs/overseer/images/session-lockTree-20nodes.pngdiff --git a/solr/dev-docs/overseer/images/session-lockTree1.png b/dev-docs/overseer/images/session-lockTree1.pngsimilarity index 100%rename from solr/dev-docs/overseer/images/session-lockTree1.pngrename to dev-docs/overseer/images/session-lockTree1.pngdiff --git a/solr/dev-docs/overseer/images/session-lockTree2.png b/dev-docs/overseer/images/session-lockTree2.pngsimilarity index 100%rename from solr/dev-docs/overseer/images/session-lockTree2.pngrename to dev-docs/overseer/images/session-lockTree2.pngdiff --git a/solr/dev-docs/overseer/images/single-thread-clusterstate-updater.png b/dev-docs/overseer/images/single-thread-clusterstate-updater.pngsimilarity index 100%rename from solr/dev-docs/overseer/images/single-thread-clusterstate-updater.pngrename to dev-docs/overseer/images/single-thread-clusterstate-updater.pngdiff --git a/solr/dev-docs/overseer/images/state-change-steps.png b/dev-docs/overseer/images/state-change-steps.pngsimilarity index 100%rename from solr/dev-docs/overseer/images/state-change-steps.pngrename to dev-docs/overseer/images/state-change-steps.pngdiff --git a/solr/dev-docs/overseer/overseer.adoc b/dev-docs/overseer/overseer.adocsimilarity index 100%rename from solr/dev-docs/overseer/overseer.adocrename to dev-docs/overseer/overseer.adocdiff --git a/solr/cloud-dev/cloud.sh b/dev-tools/scripts/cloud.shold mode 100644new mode 100755similarity index 96%rename from solr/cloud-dev/cloud.shrename to dev-tools/scripts/cloud.shindex 76f908099bb..38f9d6c84ef--- a/solr/cloud-dev/cloud.sh+++ b/dev-tools/scripts/cloud.sh@@ -7,11 +7,11 @@# previous testing. It also enables redeployment of the code for such testing# clusters without erasing the data previously indexed.#-# It is for dev testing only NOT for production use.+# It is for dev testing only, NOT for production use.#-# This is also NOT meant to be run from this directory within a lucene-solr+# This is also NOT meant to be run from this directory within a solr# working copy. Typical usage is to copy it out to a separate workspace-# such as (<GIT_CHECKOUT>/../testing) and edit then either use the -w option+# such as (<GIT_CHECKOUT>/../solr-testing) and edit then either use the -w option# or edit the definition of DEFAULT_VCS_WORKSPACE variable below.## Usage:@@ -19,7 +19,7 @@## Options:# -c clean the data & zk collections erasing all indexed data-# -r recompile server with 'ant clean server create-package'+# -r recompile server with 'gradlew clean assembleDist'# -m <mem> memory per node# -a <args> additional JVM options# -n <num> number of nodes to create/start if this doesn't match error@@ -53,10 +53,10 @@# directory as this script. Distant paths with slashes or funny characters# *might* work, but are not well tested, YMMV.#-# PEREQ: 1. Zookeeper on localhost:2181 (or as specified by -z option) where+# PREREQ: Zookeeper on localhost:2181 (or as specified by -z option) where# it is ok to create a lot of top level directories named for# the absolute path of the [name] directory (for example:-# /solr_home_myuser_projects_solr_testing_2019-01-01) Note+# /solr_home_myuser_projects_solr_testing_2019-01-01). Note# that not using the embedded zookeeper is key to being able# switch between testing setups and to test vs alternate versions# of zookeeper if desired.@@ -65,7 +65,6 @@# testing installations of solr.# 2. Edit DEFAULT_VCS_WORKSPACE if the present value does not suit# your purposes.-# 3. chmod +x cloud.sh## EXAMPLES:#@@ -91,7 +90,7 @@###################################################################################-DEFAULT_VCS_WORKSPACE='../code/lucene-solr'+DEFAULT_VCS_WORKSPACE='../solr'############## Normally no need to edit below this line ##############@@ -388,4 +387,4 @@ case ${COMMAND} instart;;*) echo "Invalid command $COMMAND"; exit 2;-esac\ No newline at end of file+esacdiff --git a/solr/dev-docs/README.adoc b/solr/dev-docs/README.adocdeleted file mode 100644index 4abc87a1181..00000000000--- a/solr/dev-docs/README.adoc+++ /dev/null@@ -1,19 +0,0 @@-= Solr Developer Docs-// Licensed to the Apache Software Foundation (ASF) under one-// or more contributor license agreements. See the NOTICE file-// distributed with this work for additional information-// regarding copyright ownership. The ASF licenses this file-// to you under the Apache License, Version 2.0 (the-// "License"); you may not use this file except in compliance-// with the License. You may obtain a copy of the License at-//-// http://www.apache.org/licenses/LICENSE-2.0-//-// Unless required by applicable law or agreed to in writing,-// software distributed under the License is distributed on an-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY-// KIND, either express or implied. See the License for the-// specific language governing permissions and limitations-// under the License.--This directory includes information for Solr developers.