You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@solr.apache.org by ep...@apache.org on 2021/04/14 20:18:06 UTC
[solr] branch main updated: SOLR-12930: Simplify and Organize
Developer Docs (#69)
This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/main by this push:
new 04ad095 SOLR-12930: Simplify and Organize Developer Docs (#69)
04ad095 is described below
commit 04ad0955e70d6d5657e6418e95469cf52adb83ea
Author: Eric Pugh <ep...@opensourceconnections.com>
AuthorDate: Wed Apr 14 16:17:56 2021 -0400
SOLR-12930: Simplify and Organize Developer Docs (#69)
* Consolidate developer docs into top level /dev-docs, and provide a single pointer to other places that host developer oriented docs.
* Some small tweaks to the cloud testing script.
---
dev-docs/FAQ.adoc | 11 ++++++++++
dev-docs/README.adoc | 16 +++++++++++---
dev-docs/{dev-utilities.adoc => cloud-script.adoc} | 24 +++++++++++----------
.../overseer/images/configSet-processor-flow.png | Bin
.../overseer/images/locking-levels.png | Bin
.../overseer/images/session-lockTree-20nodes.png | Bin
.../overseer/images/session-lockTree1.png | Bin
.../overseer/images/session-lockTree2.png | Bin
.../images/single-thread-clusterstate-updater.png | Bin
.../overseer/images/state-change-steps.png | Bin
{solr/dev-docs => dev-docs}/overseer/overseer.adoc | 0
{solr/cloud-dev => dev-tools/scripts}/cloud.sh | 17 +++++++--------
solr/dev-docs/README.adoc | 19 ----------------
13 files changed, 45 insertions(+), 42 deletions(-)
diff --git a/dev-docs/FAQ.adoc b/dev-docs/FAQ.adoc
new file mode 100644
index 0000000..1ea1aa1
--- /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.adoc
index bdb7410..bb0d17d 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.adoc
similarity index 53%
rename from dev-docs/dev-utilities.adoc
rename to dev-docs/cloud-script.adoc
index fb85a25..3ff9c7f 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 -r
The 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.png
similarity index 100%
rename from solr/dev-docs/overseer/images/configSet-processor-flow.png
rename to dev-docs/overseer/images/configSet-processor-flow.png
diff --git a/solr/dev-docs/overseer/images/locking-levels.png b/dev-docs/overseer/images/locking-levels.png
similarity index 100%
rename from solr/dev-docs/overseer/images/locking-levels.png
rename to dev-docs/overseer/images/locking-levels.png
diff --git a/solr/dev-docs/overseer/images/session-lockTree-20nodes.png b/dev-docs/overseer/images/session-lockTree-20nodes.png
similarity index 100%
rename from solr/dev-docs/overseer/images/session-lockTree-20nodes.png
rename to dev-docs/overseer/images/session-lockTree-20nodes.png
diff --git a/solr/dev-docs/overseer/images/session-lockTree1.png b/dev-docs/overseer/images/session-lockTree1.png
similarity index 100%
rename from solr/dev-docs/overseer/images/session-lockTree1.png
rename to dev-docs/overseer/images/session-lockTree1.png
diff --git a/solr/dev-docs/overseer/images/session-lockTree2.png b/dev-docs/overseer/images/session-lockTree2.png
similarity index 100%
rename from solr/dev-docs/overseer/images/session-lockTree2.png
rename to dev-docs/overseer/images/session-lockTree2.png
diff --git a/solr/dev-docs/overseer/images/single-thread-clusterstate-updater.png b/dev-docs/overseer/images/single-thread-clusterstate-updater.png
similarity index 100%
rename from solr/dev-docs/overseer/images/single-thread-clusterstate-updater.png
rename to dev-docs/overseer/images/single-thread-clusterstate-updater.png
diff --git a/solr/dev-docs/overseer/images/state-change-steps.png b/dev-docs/overseer/images/state-change-steps.png
similarity index 100%
rename from solr/dev-docs/overseer/images/state-change-steps.png
rename to dev-docs/overseer/images/state-change-steps.png
diff --git a/solr/dev-docs/overseer/overseer.adoc b/dev-docs/overseer/overseer.adoc
similarity index 100%
rename from solr/dev-docs/overseer/overseer.adoc
rename to dev-docs/overseer/overseer.adoc
diff --git a/solr/cloud-dev/cloud.sh b/dev-tools/scripts/cloud.sh
old mode 100644
new mode 100755
similarity index 96%
rename from solr/cloud-dev/cloud.sh
rename to dev-tools/scripts/cloud.sh
index 76f9080..38f9d6c
--- 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} in
start
;;
*) echo "Invalid command $COMMAND"; exit 2;
-esac
\ No newline at end of file
+esac
diff --git a/solr/dev-docs/README.adoc b/solr/dev-docs/README.adoc
deleted file mode 100644
index 4abc87a..0000000
--- 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.