Clarify the limitations of gerrit+ssh in replication.config

The gerrit+ssh option, introduced years ago when Lucene was not
used in Gerrit, is currently misunderstood by the users because
it is presented as a way to perform Gerrit master to master
replication.

Whilst it was actually possible in the past, it isn't supported
anymore because of the need of more machinery around it.

Clarify the limitations in the documentation and warn on the
limited applicability.

Bug: Issue 12616
Change-Id: I992385b9da03b0c3c2b938817687ba50b2dbde58

1 files changed, 22 insertions, 6 deletions

diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md
index c9356b0..1309aeb 100644
--- a/src/main/resources/Documentation/config.md
+++ b/src/main/resources/Documentation/config.md
@@ -177,17 +177,33 @@ remote.NAME.adminUrl
 	local environment.  In that case, an alternative SSH url could
 	be specified to repository creation.
 
-	To enable replication to different Gerrit instance use `gerrit+ssh://`
+	*Backward compatibility notice*
+
+	Before Gerrit v2.13 it was possible to enable replication to different
+	Gerrit masters using `gerrit+ssh://`
 	as protocol name followed by hostname of another Gerrit server eg.
 
 	`gerrit+ssh://replica1.my.org/`
 
-	In this case replication will use Gerrit's SSH API to
-	create/remove projects and update repository HEAD references.
-
-	NOTE: In order to replicate project deletion, the
+	In that case replication would have used Gerrit's SSH API to
+	create/remove projects and update repository HEAD references
+	and, in order to replicate project deletion, the
 	link:https://gerrit-review.googlesource.com/admin/projects/plugins/delete-project delete-project[delete-project]
-	plugin must be installed on the other Gerrit.
+	plugin was needed to be installed on the other Gerrit.
+
+	The `gerrit+ssh` option is kept for backward compatibility, however
+	the use-case behind it is not valid anymore since the introduction of
+	Lucene indexes and the removal of ReviewDb, which would require
+	a lot more machinery to setup a master to master replication scenario.
+
+	The `gerrit+ssh` option is still possible but is limited to the
+	ability to replicate only regular Git repositories that do not
+	contain any code-review or NoteDb information.
+
+	Using `gerrit+ssh` for replicating all Gerrit repositories
+	would result in failures on the All-Users.git replication and
+	would not be able to replicate changes magic refs and indexes
+	across nodes.
 
 remote.NAME.receivepack
 :	Path of the `git-receive-pack` executable on the remote