Explain limitation of storing plugin config in existing config files

In the plugin documentation it is suggested to store plugin
configuration parameters in a 'plugin' subsection in
'gerrit.config'/'project.config'. This approach has the limitation
that the plugin configuration cannot have subsections and thus it is
only suitable for plugins with a simple key-value pair configuration.
Plugins that have a more complex configuration need to store their
configuration in an own configuration file.

Change-Id: Iac305e1bb451496034b06dbc762c8da08c97a59e
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>

1 files changed, 22 insertions, 0 deletions

diff --git a/Documentation/dev-plugins.txt b/Documentation/dev-plugins.txt
index af087477dc..7a35115e1f 100644
--- a/Documentation/dev-plugins.txt
+++ b/Documentation/dev-plugins.txt
@@ -450,6 +450,17 @@ In Gerrit, global configuration is stored in the `gerrit.config` file.
 If a plugin needs global configuration, this configuration should be
 stored in a `plugin` subsection in the `gerrit.config` file.
 
+This approach of storing the plugin configuration is only suitable for
+plugins that have a simple configuration that only consists of
+key-value pairs. With this approach it is not possible to have
+subsections in the plugin configuration. Plugins that require a complex
+configuration need to store their configuration in their own
+configuration file where they can make use of subsections. On the other
+hand storing the plugin configuration in a 'plugin' subsection in the
+`gerrit.config` file has the advantage that administrators have all
+configuration parameters in one file, instead of having one
+configuration file per plugin.
+
 To avoid conflicts with other plugins, it is recommended that plugins
 only use the `plugin` subsection with their own name. For example the
 `helloworld` plugin should store its configuration in the
@@ -485,6 +496,17 @@ needs configuration on project level (e.g. to enable its functionality
 only for certain projects), this configuration should be stored in a
 `plugin` subsection in the project's `project.config` file.
 
+This approach of storing the plugin configuration is only suitable for
+plugins that have a simple configuration that only consists of
+key-value pairs. With this approach it is not possible to have
+subsections in the plugin configuration. Plugins that require a complex
+configuration need to store their configuration in their own
+configuration file where they can make use of subsections. On the other
+hand storing the plugin configuration in a 'plugin' subsection in the
+`project.config` file has the advantage that project owners have all
+configuration parameters in one file, instead of having one
+configuration file per plugin.
+
 To avoid conflicts with other plugins, it is recommended that plugins
 only use the `plugin` subsection with their own name. For example the
 `helloworld` plugin should store its configuration in the