Move the association policy to the plugin's config

The association policy was incorrectly set in Gerrit's own commentLink, by hijacking a native configuration section.

Move the association to the canonical place, [plugin "@PLUGIN@"],
keeping the legacy configuration still supported as fallback.

Change-Id: I13c0ef2941d0cad022d7000032d1759265e111a7

src/main/java/com/googlesource/gerrit/plugins/its/base/its/ItsConfig.java

diff --git a/src/main/java/com/googlesource/gerrit/plugins/its/base/its/ItsConfig.java b/src/main/java/com/googlesource/gerrit/plugins/its/base/its/ItsConfig.java
index 06b2b77..1241b8a 100644
--- a/src/main/java/com/googlesource/gerrit/plugins/its/base/its/ItsConfig.java
+++ b/src/main/java/com/googlesource/gerrit/plugins/its/base/its/ItsConfig.java
@@ -198,7 +198,11 @@
    * @return policy on how necessary association with issues is
    */
   public ItsAssociationPolicy getItsAssociationPolicy() {
-    return gerritConfig.getEnum("commentlink", getCommentLinkName(),
-        "association", ItsAssociationPolicy.OPTIONAL);
+    ItsAssociationPolicy legacyAssociatonPolicy =
+        gerritConfig.getEnum("commentlink", getCommentLinkName(),
+            "association", ItsAssociationPolicy.OPTIONAL);
+
+    return gerritConfig.getEnum("plugin", pluginName, "association",
+        legacyAssociatonPolicy);
   }
 }

src/main/resources/Documentation/config-common.md

diff --git a/src/main/resources/Documentation/config-common.md b/src/main/resources/Documentation/config-common.md
index 02565e3..bf36852 100644
--- a/src/main/resources/Documentation/config-common.md
+++ b/src/main/resources/Documentation/config-common.md
@@ -26,7 +26,6 @@
 [commentlink "@PLUGIN@"]
     match = [Bb][Uu][Gg][ ]*([1-9][0-9]*)
     html = "<a href=\"http://my.issure.tracker.example.org/show_bug.cgi?id=$1\">(bug $1)</a>"
-    association = SUGGESTED
 ```
 
 in `etc/gerrit.config` would allow to match the issues `4711`, `167`
@@ -36,7 +35,9 @@
 Sample commit message relating to bug 4711, and bug 167.
 ```
 
-By setting a `commentlink`'s `association` (see above's example), it
+[upstream-comment-link-doc]: ../../../Documentation/config-gerrit.html#commentlink
+
+By setting a `commentlink`'s `association` on the plugin's @PLUGIN@ configuration, it
 is possible to require commits to carry ITS references; the following
 values are supported (default is `OPTIONAL`):
 
@@ -52,9 +53,20 @@
 :	 Bug-ids are liked when found in the git commit message, no warning is
 	 displayed otherwise.
 
-[upstream-comment-link-doc]: ../../../Documentation/config-gerrit.html#commentlink
+Example:
 
+```
+[plugin "@PLUGIN@"]
+    association = MANDATORY
+```
 
+in `etc/gerrit.config` would accept only commits that contain a valid issue id
+in the comment, matching the commentLink defined previously.
+
+NOTE: Historically the association has been defined in the Gerrit's commentLink
+section. That setting is deprecated but still supported for the current release.
+You are encouraged to move the association policy to the plugin section, the
+commentLink.association will be discontinued in the next major release.
 
 [enabling-its-integration]: #enabling-its-integration
 <a name="enabling-its-integration">Enabling ITS integration</a>