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@"]