Merge branch 'stable-3.1' into stable-3.2
* stable-3.1:
e2e-tests: Clarify replication_delay usage in documentation
e2e-tests: Clarify the documented purpose of uppercase keys in json file
NoteDbMigrator: Improve log message when saving ref updates
e2e-tests: Move plugin list documentation to own section for readability
e2e-tests: Formalize power_factor documentation section for readability
NoteDbMigrator: fix formatting
Change-Id: Ib1fd6c4e61fa2e02d2d81be474b4a54408da07e2
diff --git a/Documentation/dev-e2e-tests.txt b/Documentation/dev-e2e-tests.txt
index 3f99642..d35de80 100644
--- a/Documentation/dev-e2e-tests.txt
+++ b/Documentation/dev-e2e-tests.txt
@@ -126,7 +126,8 @@
file contains the commands and repository used during the e2e test. That file currently looks like
below. This scenario serves as a simple example with no actual load in it. It can be used to test
or validate the local setup. More complex scenarios can be further developed, under the
-`com.google.gerrit.scenarios` package. The uppercase keywords are discussed further below.
+`com.google.gerrit.scenarios` package. The uppercase keywords are set through
+link:#_environment_properties[environment properties,role=external,window=_blank].
----
[
@@ -173,14 +174,42 @@
* `-Dcom.google.gerrit.scenarios.ssh_port=29418`
* `-Dcom.google.gerrit.scenarios.http_port=8080`
* `-Dcom.google.gerrit.scenarios.http_scheme=http`
-* `-Dcom.google.gerrit.scenarios.replication_delay=15`
Above, the properties can be set with values matching specific deployment topologies under test.
-The example values shown above are the currently coded default ones. For example, the `http` scheme
-above could be replaced with `https`. The `replication_delay` property matches replication plugin's
-configuration with the same name. The framework may support differing or more properties over time.
+The name of the property corresponds to the uppercase keyword found in the json file. For example,
+`hostname` above will set the value of `HOSTNAME` in the
+link:#_input_file[aforementioned example,role=external,window=_blank].
-Plugin or otherwise non-core scenarios may do so just as well. The core java package
+The example values shown above are the currently coded default ones. For example, the `http` scheme
+above could be replaced with `https`. The framework may support differing or more properties over time.
+
+==== Replication delay
+
+The `replication_delay` property allows test scenario steps to wait for that many seconds, prior to
+expecting a done replication. Its default is `15` seconds and can be set using another value:
+
+* `-Dcom.google.gerrit.scenarios.replication_delay=15`
+
+There is a short time buffer added to this property. Now, the replication starts after replication
+plugin's own `replicationDelay`, in seconds, and typically takes some more seconds to complete.
+That whole replication time depends on the system under test. Therefore, this property here should
+be set to a value high enough, so that the test checks for a done replication at the right time.
+
+==== Automatic properties
+
+The link:#_input_file[example keywords,role=external,window=_blank] also include `_PROJECT`,
+prefixed with an underscore, which means that its value gets automatically generated by the
+scenario. Any property setting for it is therefore not applicable. Its usage differs from the
+non-prefixed `PROJECT` keyword, in that sense. Using the latter instead in json files requires
+setting this `JAVA_OPTS` property:
+
+* `-Dcom.google.gerrit.scenarios.project=myOwnTestRepoProjectName`
+
+Other automatic keys may be used and implemented, always prefixed with an underscore that tells so.
+
+==== Plugin scenarios
+
+Plugin or otherwise non-core scenarios can also use such properties. The core java package
`com.google.gerrit.scenarios` from the example above has to be replaced with the one under which
those scenario classes are. Such extending scenarios can also add extension-specific properties.
Examples of this can be found in these Gerrit plugins test code:
@@ -190,9 +219,7 @@
* `link:https://gerrit.googlesource.com/plugins/multi-site[multi-site,role=external,window=_blank]`
* `link:https://gerrit.googlesource.com/plugins/rename-project[rename-project,role=external,window=_blank]`
-Further above, the `_PROJECT` keyword is prefixed with an underscore, which means that its value
-gets automatically generated by the scenario. Any property setting for it is therefore not
-applicable. Its usage differs from the non-prefixed `PROJECT` keyword, in that sense.
+==== Power factor
The following core property can be optionally set depending on the runtime environment. The test
environments used as reference for scenarios development assume its default value, `1.0`. For
