Support project level plugin configuration
Some plugins need a configuration on project level (e.g. for
'plugins/reviewers-by-blame' the max number of reviewers that should
be automatically added should be configured per project). The idea is
to store this configuration in project.config inside a "plugin"
section having a subsection per plugin. E.g.:
[plugin "reviewers-by-blame"]
maxReviewers = 3
It should be avoided that each plugin needs to parse 'project.config'
on its own. It is also difficult from a plugin to cache the
configuration parameters as the plugin doesn't know when the
'project.config' file is updated.
Extend ProjectConfig so that it automatically parses all 'plugin'
sections on load. The values of these sections are stored internally
and can easily be accessed from a plugin, e.g.:
int maxReviewers = pluginConfigFactory
.get(project, "reviewers-by-blame")
.getInt("maxReviewers", 0);
Change-Id: I802f38a4d41814a51d40d41eb7824637c7e34948
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/dev-plugins.txt b/Documentation/dev-plugins.txt
index 64c9bff..c0abf9a 100644
--- a/Documentation/dev-plugins.txt
+++ b/Documentation/dev-plugins.txt
@@ -366,6 +366,45 @@
.getString("language", "English");
----
+[[project-specific-configuration]]
+Project Specific Configuration
+------------------------------
+
+In Gerrit, project specific configuration is stored in the project's
+`project.config` file on the `refs/meta/config` branch. If a plugin
+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.
+
+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
+`plugin.helloworld` subsection:
+
+----
+ [plugin "helloworld"]
+ enabled = true
+----
+
+Via the `com.google.gerrit.server.config.PluginConfigFactory` class a
+plugin can easily access its project specific configuration and there
+is no need for a plugin to parse the `project.config` file on its own:
+
+[source,java]
+----
+ @Inject
+ private com.google.gerrit.server.config.PluginConfigFactory cfg;
+
+ ...
+
+ boolean enabled = cfg.get(project, "helloworld")
+ .getBoolean("enabled", false);
+----
+
+Project owners can edit the project configuration by fetching the
+`refs/meta/config` branch, editing the `project.config` file and
+pushing the commit back.
+
[[capabilities]]
Plugin Owned Capabilities
-------------------------
