From a0818d5ab2669dfd7f6bf8ca9e0ec8d8e0148b5d Mon Sep 17 00:00:00 2001
From: Andreas Dangel <andreas.dangel@pmd-code.org>
Date: Fri, 4 Oct 2024 15:54:21 +0200
Subject: [PATCH] [doc] Document renamed/old rule names

---
 docs/pages/release_notes.md                          |  8 ++++++++
 .../main/resources/category/java/bestpractices.xml   | 12 ++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md
index 08ed81281f..197b7a4aec 100644
--- a/docs/pages/release_notes.md
+++ b/docs/pages/release_notes.md
@@ -36,6 +36,14 @@ The old rule names still work but are deprecated.
   * [#5067](https://github.com/pmd/pmd/issues/5067): \[java] CloseResource: False positive for FileSystems.getDefault()
 
 ### 🚨 API Changes
+* java-bestpractices
+  * The old rule name `JUnit4TestShouldUseAfterAnnotation` has been deprecated. Use the new name {% rule java/bestpractices/UnitTestShouldUseAfterAnnotation %} instead.
+  * The old rule name `JUnit4TestShouldUseBeforeAnnotation` has been deprecated. Use the new name {% rule java/bestpractices/UnitTestShouldUseBeforeAnnotation %} instead.
+  * The old rule name `JUnit4TestShouldUseTestAnnotation` has been deprecated. Use the new name {% rule java/bestpractices/UnitTestShouldUseTestAnnotation %} instead.
+  * The old rule name `JUnitAssertionsShouldIncludeMessage` has been deprecated. Use the new name {% rule java/bestpractices/UnitTestAssertionsShouldIncludeMessage %} instead.
+  * The old rule name `JUnitTestContainsTooManyAsserts` has been deprecated. Use the new name {% rule java/bestpractices/UnitTestContainsTooManyAsserts %} instead.
+  * The old rule name `JUnitTestsShouldIncludeAssert` has been deprecated. Use the new name {% rule java/bestpractices/UnitTestShouldIncludeAssert %} instead.
+
 
 ### ✨ Merged pull requests
 * [#4965](https://github.com/pmd/pmd/pull/4965): \[java] Rename JUnit rules with overly restrictive names - [Juan Martín Sotuyo Dodero](https://github.com/jsotuyod) (@jsotuyod)
diff --git a/pmd-java/src/main/resources/category/java/bestpractices.xml b/pmd-java/src/main/resources/category/java/bestpractices.xml
index aa2f4e7255..03b23ad1ca 100644
--- a/pmd-java/src/main/resources/category/java/bestpractices.xml
+++ b/pmd-java/src/main/resources/category/java/bestpractices.xml
@@ -1239,6 +1239,8 @@ Unit assertions should include an informative message - i.e., use the three-argu
 `assertEquals()`, not the two-argument version.
 
 This rule supports tests using JUnit (3, 4 and 5) and TestNG.
+
+Note: This rule was named JUnitAssertionsShouldIncludeMessage before PMD 7.7.0.
         </description>
         <priority>3</priority>
         <example>
@@ -1268,6 +1270,8 @@ public class Foo {
             Customize the maximum number of assertions used by this Rule to suit your needs.
 
             This rule checks for JUnit (3, 4 and 5) and TestNG Tests.
+
+            Note: This rule was named JUnitTestContainsTooManyAsserts before PMD 7.7.0.
         </description>
         <priority>3</priority>
         <example>
@@ -1303,6 +1307,8 @@ public class MyTestCase {
             with messages provide the developer a clearer idea of what the test does.
 
             This rule checks for JUnit (3, 4 and 5) and TestNG Tests.
+
+            Note: This rule was named JUnitTestsShouldIncludeAssert before PMD 7.7.0.
         </description>
         <priority>3</priority>
         <example>
@@ -1333,6 +1339,8 @@ public class Foo {
 
             JUnit 4 will only execute methods annotated with `@After` after running each test.
             JUnit 5 introduced `@AfterEach` and `@AfterAll` annotations to execute methods after each test or after all tests in the class, respectively.
+
+            Note: This rule was named JUnit4TestShouldUseAfterAnnotation before PMD 7.7.0.
         </description>
         <priority>3</priority>
         <properties>
@@ -1380,6 +1388,8 @@ public class MyTest2 {
 
             JUnit 4 will only execute methods annotated with `@Before` before all tests.
             JUnit 5 introduced `@BeforeEach` and `@BeforeAll` annotations to execute methods before each test or before all tests in the class, respectively.
+
+            Note: This rule was named JUnit4TestShouldUseBeforeAnnotation before PMD 7.7.0.
         </description>
         <priority>3</priority>
         <properties>
@@ -1426,6 +1436,8 @@ public class MyTest2 {
             In JUnit 4, only methods annotated with the `@Test` annotation are executed.
             In JUnit 5, one of the following annotations should be used for tests: `@Test`, `@RepeatedTest`, `@TestFactory`, `@TestTemplate` or `@ParameterizedTest`.
             In TestNG, only methods annotated with the `@Test` annotation are executed.
+
+            Note: This rule was named JUnit4TestShouldUseTestAnnotation before PMD 7.7.0.
         </description>
         <priority>3</priority>
         <properties>