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>
diff --git a/Documentation/dev-plugins.txt b/Documentation/dev-plugins.txt
index af08747..7a35115 100644
--- a/Documentation/dev-plugins.txt
+++ b/Documentation/dev-plugins.txt
@@ -450,6 +450,17 @@
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 @@
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
