[java] Deprecate AvoidFinalLocalVariable

Fixes #1612, Refs #1482

docs/pages/release_notes.md

@@ -59,6 +59,14 @@ Table aliases are now supported when specifying columns in INSERT INTO clauses.
     non static initializers in anonymous classes anymore. For this use case, there is a new rule now:
     {% rule "java/bestpractices/DoubleBraceInitialization" %} (`java-bestpractices`).
 
+#### Deprecated Rules
+
+*   The Java rule {% rule "java/codestyle/AvoidFinalLocalVariable" %} (`java-codestyle`) has been deprecated
+    and will be removed with PMD 7.0.0. The rule is controversial and also contradicts other existing
+    rules such as {% rule "java/codestyle/LocalVariableCouldBeFinal" %}. If the goal is to avoid defining
+    constants in a scope smaller than the class, then the rule {% rule "java/errorprone/AvoidDuplicateLiterals" %}
+    should be used instead.
+
 ### Fixed Issues
 
 *   apex
@@ -69,6 +77,8 @@ Table aliases are now supported when specifying columns in INSERT INTO clauses.
     *   [#1703](https://github.com/pmd/pmd/issues/1703): \[java] UnusedPrivateField on member annotated with lombok @Delegate
     *   [#1845](https://github.com/pmd/pmd/issues/1845): \[java] Regression in MethodReturnsInternalArray not handling enums
     *   [#1854](https://github.com/pmd/pmd/issues/1854): \[java] Rule to check for double brace initialisation
+*   java-codestyle
+    *   [#1612](https://github.com/pmd/pmd/issues/1612): \[java] Deprecate AvoidFinalLocalVariable
 *   java-design
     *   [#1094](https://github.com/pmd/pmd/issues/1094): \[java] UseUtilityClass should be LombokAware
 *   java-errorprone
@@ -110,6 +120,7 @@ of deprecations.
 
 ### External Contributions
 
+*   [#1482](https://github.com/pmd/pmd/pull/1482): \[java] Explain the existence of AvoidFinalLocalVariable in it's description - [Karl-Philipp Richter](https://github.com/krichter722)
 *   [#1792](https://github.com/pmd/pmd/pull/1792): \[java] Added lombok.experimental to AbstractLombokAwareRule - [jakivey32](https://github.com/jakivey32)
 *   [#1808](https://github.com/pmd/pmd/pull/1808): \[plsql] Fix PL/SQL Syntax errors - [Hugo Araya Nash](https://github.com/kabroxiko)
 *   [#1829](https://github.com/pmd/pmd/pull/1829): \[java] Fix false negative in UnsynchronizedStaticFormatter - [Srinivasan Venkatachalam](https://github.com/Srini1993)

pmd-java/src/main/resources/category/java/codestyle.xml

@@ -92,10 +92,24 @@ public class Fo$o {  // not a recommended name
     <rule name="AvoidFinalLocalVariable"
           language="java"
           since="4.1"
+          deprecated="true"
           class="net.sourceforge.pmd.lang.rule.XPathRule"
           message="Avoid using final local variables, turn them into fields"
           externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_codestyle.html#avoidfinallocalvariable">
-        <description><![CDATA[Avoid using final local variables, turn them into fields. Note that this is a controversial rule which is merely useful to enforce a certain code style (which is contradictory to good coding practices in most of the cases it's applied to) and avoid local literals being declared in a scope smaller than the class. The rule is destined to be moved to the "controversial" ruleset again or removed alltogether, but not until 7.0.0, see https://github.com/pmd/pmd/issues/811 for the discussion about that.]]></description>
+        <description>
+Avoid using final local variables, turn them into fields.
+
+Note that this is a controversial rule which is merely useful to enforce a certain code style
+(which is contradictory to good coding practices in most of the cases it's applied to) and
+avoid local literals being declared in a scope smaller than the class.
+
+Also note, that this rule is the opposite of {% rule "java/codestyle/LocalVariableCouldBeFinal" %}.
+Having both rules enabled results in contradictory violations being reported.
+
+This rule is deprecated and will be removed with PMD 7.0.0. There is no replacement planned.
+If the goal is to avoid defining constants in a scope smaller than the class, then the rule
+{% rule "java/errorprone/AvoidDuplicateLiterals" %} should be used instead.
+        </description>
         <priority>3</priority>
         <properties>
             <property name="xpath">