Revise the documentation to improve readability and ensure accuracy
Change-Id: Ifa5c43a96dd7f179134f6428a3bd0cbd8c59b8f3
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
index 399da4f..b459a0a 100644
--- a/src/main/resources/Documentation/about.md
+++ b/src/main/resources/Documentation/about.md
@@ -1,4 +1,6 @@
-Provides the ability to rename a project.
+The @PLUGIN@ plugin provides the ability to rename a Gerrit project, including
+its Git repository and all associated changes. It supports replication of
+renames across Gerrit replicas via SSH or HTTP.
Note: The project state is set to READ_ONLY at the start of the rename operation.
If the rename operation fails, the project state is reverted back to ACTIVE.
@@ -10,54 +12,32 @@
* You cannot rename projects that use "submodule subscription"
- Projects that use submodule subscription cannot be renamed.
- Remove the submodule registration before attempting to rename the project.
-
* You cannot rename projects that have any child projects
- Projects that have child projects cannot be renamed. Currently, the
- plugin does not support rename of parent projects.
-
* You cannot rename using a project name that already exists
- If choosing a name that already exists, you cannot rename the project.
-
* You cannot rename the "All-Projects" project
- If choosing to rename "All-Projects", you cannot rename the project as this action is prohibited.
-
* You cannot rename the "All-Users" project
- If choosing to rename "All-Users", you cannot rename the project as this action is prohibited.
-
-* You should limit project renames to administrator users
-
- Because of all the above caveats, it is not recommended to allow any non-admin
- user to perform any project rename.
-
Replication of project renaming
-------------------------------
This plugin can replicate project renaming by itself, if `gerrit.config` has a `url` entry at the
plugin configuration section and if master and all other replicas have this plugin installed. Once
configured, replication of rename will start on every successful renaming of a local project. When
-the plugin completes the renaming operation on the master instance successfully, it sends an ssh
-command to replicas' rename-project plugin using the hostname provided in the configuration file.
-Replicas then perform their own local file system rename.
+the plugin completes the renaming operation on the master instance successfully, it sends an SSH
+command or HTTP request to replicas' rename-project plugin using the hostname provided in the
+configuration file. Replicas then perform their own local file system rename.
-The ssh rename replication will retry as many times as provided by the configuration parameter
+For more details on how to configure replication, see the [Configuration](config.md) documentation.
+
+The rename replication will retry as many times as provided by the configuration parameter
`renameReplicationRetries`. The default value is 3 and can be configured in `gerrit.config`.
-If ssh rename replication fails after the mentioned number of retries, the plugin stops retrying
+If rename replication fails after the mentioned number of retries, the plugin stops retrying
the rename replication operation and logs the error. This results in primary and replica instances
-being out of sync. The admin then will have to consider the following steps:
-
-1. Start replication on the renamed project from the primary side. For more information, see the
-[replication start command](../../replication/Documentation/cmd-start.md).
-
-2. Confirm that the renamed project was replicated.
-
-3. Delete the original (not renamed) project repository directory contents on the replica side; this
-step is optional.
+being out of sync. The admin then will have to manually perform the rename operation on the replica
+instance.
Access
------
@@ -67,5 +47,7 @@
plugin) or the 'Administrate Server' capability. Project owners are
allowed to rename their own projects if they are members of a group that
is granted the 'Rename Own Project' capability (provided by this
-plugin). However, because of all the caveats of this plugin, it is not
+plugin).
+
+However, because of all the [caveats](#limitations) of this plugin, it is not
recommended to delegate the 'Rename Project' capability to any non-admin user.
diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md
index b4ec9b2..293952e 100644
--- a/src/main/resources/Documentation/config.md
+++ b/src/main/resources/Documentation/config.md
@@ -29,7 +29,7 @@
prefix followed by hostname and then port number after `:`. It is also possible
to specify the ssh user by passing `USERNAME@` as a prefix for hostname.
-Rename replication is done over SSH, so ensure the host key of the remote
+If rename replication is done over SSH, ensure the host key of the remote
system(s) is already in the Gerrit user's `~/.ssh/known_hosts` file. The easiest
way to add the host key is to connect once by hand with the command line:
@@ -43,8 +43,8 @@
* `sshConnectionTimeout` : Timeout for SSH connections in minutes. If 0, there
is no timeout, and the client waits indefinitely. By default, 2 minutes.
-To configure http replication, provide the correct url. To cpecify username and
-password for replication for rename, add password and username in gerrit.config
+To configure http replication, provide the correct url. To specify username and
+password for replication for rename, add `password` and `user` options in gerrit.config
or secure.config. for example:
```
[plugin "@PLUGIN@"]
