Improve plugin documentation
Change-Id: I9d54838b1588705ab3a57ff07995f4d0c3441108
diff --git a/README.md b/README.md
index fe8a86f..3e57d63 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,25 @@
# Gerrit multi-site plugin
-This plugin allows having multiple Gerrit masters to be deployed across various
-sites without having to share any storage. The alignment between the masters
-happens using the replication plugin and an external message broker.
+This plugin allows to deploy a distributed cluster of multiple Gerrit masters
+each using a separate site without sharing any storage. The alignment between
+the masters happens using the replication plugin and an external message broker.
-The Gerrit masters requirements are:
+Requirements for the Gerrit masters are:
- Gerrit v2.16.5 or later
- Migrated to NoteDb
- Connected to the same message broker
-- Accessible behind a load balancer (e.g., HAProxy)
+- Accessible via a load balancer (e.g. HAProxy)
**NOTE**: The multi-site plugin will not start if Gerrit is not yet migrated
to NoteDb.
Currently, the only mode supported is one primary read/write master
-and multiple read-only masters but eventually the plan is to support N
+and multiple read-only masters but eventually the plan is to support multiple
read/write masters. The read/write master is handling any traffic while the
read-only masters are serving the Gerrit GUI assets, the HTTP GET REST API and
-the git-upload-packs. The read-only masters are kept updated to be always ready
-to become a read/write master.
+git fetch requests (git-upload-pack). The read-only masters are kept synchronized
+with the read/write master in order to be always ready to become a read/write master.
For more details on the overall multi-site design and roadmap, please refer
to the [multi-site plugin DESIGN.md document](DESIGN.md)
@@ -102,6 +102,6 @@
For more details on the configuration settings, please refer to the
[multi-site configuration documentation](src/main/resources/Documentation/config.md).
-You need also to setup the Git-level replication between nodes, for more details
+You also need to setup the Git-level replication between nodes, for more details
please refer to the
[replication plugin documentation](https://gerrit.googlesource.com/plugins/replication/+/refs/heads/master/src/main/resources/Documentation/config.md).
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
index 9e29e71..93154d6 100644
--- a/src/main/resources/Documentation/about.md
+++ b/src/main/resources/Documentation/about.md
@@ -16,7 +16,7 @@
read-only masters but eventually the plan is to support `n` read/write masters.
The read/write master is handling any traffic while the
read-only masters are serving the Gerrit GUI assets, the HTTP GET REST API and
-the git-upload-packs. They read-only masters are kept updated to be always
+git-upload-pack. The read-only masters are kept updated to be always
ready to become a read/write master.
The areas of alignment between the masters are:
@@ -29,7 +29,8 @@
This plugin is focussing on only the points 1. to 3., while other plugins can be
used to manage the replication of 4. across sites.
-This plugin needs to be installed in all the masters, and it will take care of
+This plugin needs to be installed as a library module in the
+`$GERRIT_SITE/lib`directory of all the masters, and it will take care of
keeping 1., 2. and 3. aligned across all the nodes.
#### Caches
diff --git a/src/main/resources/Documentation/build.md b/src/main/resources/Documentation/build.md
index f4e61d9..1dfda95 100644
--- a/src/main/resources/Documentation/build.md
+++ b/src/main/resources/Documentation/build.md
@@ -5,7 +5,7 @@
* Standalone
* In Gerrit tree
-Standalone build mode is recommended, as this mode doesn't require local Gerrit
+Standalone build mode is recommended, as this mode doesn't require a local Gerrit
tree to exist. Moreover, there are some limitations and additional manual steps
required when building in Gerrit tree mode (see corresponding sections).
@@ -44,7 +44,7 @@
This project can be imported into the Eclipse IDE:
```
- ./tools/eclipse/project.sh
+ ./tools/eclipse/project.py
```
## Build in Gerrit tree
@@ -59,7 +59,7 @@
ln -s @PLUGIN@/external_plugin_deps.bzl .
```
-From Gerrit source tree issue the command:
+From the Gerrit source tree issue the command:
```
bazel build plugins/@PLUGIN@
diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md
index 49f1b2c..e3abe59 100644
--- a/src/main/resources/Documentation/config.md
+++ b/src/main/resources/Documentation/config.md
@@ -2,8 +2,9 @@
@PLUGIN@ Configuration
=========================
-The @PLUGIN@ plugin must be installed on all the instances and the following
-fields should be specified in `$site_path/etc/@PLUGIN@.config` file:
+The @PLUGIN@ plugin must be installed as a library module in the
+`$GERRIT_SITE/lib` folder of all the instances and the following fields should
+be specified in the `$site_path/etc/@PLUGIN@.config` file:
File '@PLUGIN@.config'
--------------------
@@ -82,7 +83,7 @@
Defaults to true.
```index.numStripedLocks```
-: Number of striped locks to use for during secondary indexes reindex.
+: Number of striped locks to use during reindexing of secondary indexes.
Defaults to 10
```index.synchronize```
@@ -102,11 +103,11 @@
Defaults to 2.
```index.retryInterval```
-: The interval of time in milliseconds between the subsequent auto-retries.
+: The time interval in milliseconds between subsequent auto-retries.
Defaults to 30000 (30 seconds).
```kafka.bootstrapServers```
-: List of Kafka broker hosts:port to use for publishing events to the message
+: List of Kafka broker hosts (host:port) to use for publishing events to the message
broker
```kafka.indexEventTopic```
@@ -178,7 +179,7 @@
Defaults: true
```kafka.subscriber.pollingIntervalMs```
-: Polling interval for checking incoming events
+: Polling interval in milliseconds for checking incoming events
Defaults: 1000
@@ -187,58 +188,58 @@
Defaults: true
```ref-database.zookeeper.connectString```
-: Connection string to zookeeper
+: Connection string to Zookeeper
```ref-database.zookeeper.rootNode```
-: Root node to use under Zookeeper to store/retrieve information
+: Root node to use in Zookeeper to store/retrieve information
Defaults: "/gerrit/multi-site"
```ref-database.zookeeper.sessionTimeoutMs```
-: Root node to use under Zookeeper to store/retrieve information
+: Zookeeper session timeout in milliseconds
Defaults: 1000
```ref-database.zookeeper.connectionTimeoutMs```
-: Root node to use under Zookeeper to store/retrieve information
+: Zookeeper connection timeout in milliseconds
Defaults: 1000
```ref-database.zookeeper.retryPolicyBaseSleepTimeMs```
-: Configuration for the base sleep timeout (iun ms) to use to create the
+: Configuration for the base sleep timeout in milliseconds of the
BoundedExponentialBackoffRetry policy used for the Zookeeper connection
Defaults: 1000
```ref-database.zookeeper.retryPolicyMaxSleepTimeMs```
-: Configuration for the max sleep timeout (in milliseconds) to use to create the
+: Configuration for the maximum sleep timeout in milliseconds of the
BoundedExponentialBackoffRetry policy used for the Zookeeper connection
Defaults: 3000
```ref-database.zookeeper.retryPolicyMaxRetries```
-: Configuration for the max number of retries to use to create the
+: Configuration for the maximum number of retries of the
BoundedExponentialBackoffRetry policy used for the Zookeeper connection
Defaults: 3
```ref-database.zookeeper.casRetryPolicyBaseSleepTimeMs```
-: Configuration for the base sleep timeout (in milliseconds) to use to create the
+: Configuration for the base sleep timeout in milliseconds of the
BoundedExponentialBackoffRetry policy used for the Compare and Swap
operations on Zookeeper
Defaults: 1000
```ref-database.zookeeper.casRetryPolicyMaxSleepTimeMs```
-: Configuration for the max sleep timeout (in milliseconds) to use to create the
+: Configuration for the maximum sleep timeout in milliseconds of the
BoundedExponentialBackoffRetry policy used for the Compare and Swap
operations on Zookeeper
Defaults: 3000
```ref-database.zookeeper.casRetryPolicyMaxRetries```
-: Configuration for the max number of retries to use to create the
+: Configuration for the maximum number of retries of the
BoundedExponentialBackoffRetry policy used for the Compare and Swap
operations on Zookeeper
@@ -251,17 +252,15 @@
Defaults: 1000
-#### Custom kafka properties:
-
In addition to the above settings, custom Kafka properties can be explicitly set
for `publisher` and `subscriber`.
In order to be acknowledged, these properties need to be prefixed with the
-`KafkaProp-` prefix and then camelCased, as follows: `KafkaProp-yourPropertyValue`
+`KafkaProp-` prefix and be formatted using camel case, as follows: `KafkaProp-yourPropertyValue`
-For example, if you want to set the `auto.commit.interval.ms` property for your
-consumers, you will need to configure this property as `KafkaProp-autoCommitIntervalMs`.
+For example, if you want to set the `auto.commit.interval.ms` property for
+consumers, you need to configure this property as `KafkaProp-autoCommitIntervalMs`.
-**NOTE**: custom kafka properties will be ignored when the relevant subsection is
+**NOTE**: custom Kafka properties will be ignored when the relevant subsection is
disabled (i.e. `kafka.subscriber.enabled` and/or `kafka.publisher.enabled` are
set to `false`).
