[doc] Add the breaking change requiring user actions for 4.0 (#10612)

Co-authored-by: Daniël van Noord <13665637+DanielNoord@users.noreply.github.com>

Author: Pierre-Sassoulas

pylint/config/_breaking_changes.py

@@ -15,6 +15,8 @@ class BreakingChange(enum.Enum):
     MESSAGE_MADE_ENABLED_BY_DEFAULT = "{symbol} ({msgid}) was enabled by default"
     MESSAGE_MOVED_TO_EXTENSION = "{symbol} ({msgid}) was moved to {extension}"
     EXTENSION_REMOVED = "{extension} was removed"
+    OPTION_REMOVED = "{option} option was removed"
+    OPTION_BEHAVIOR_CHANGED = "{option} behavior changed: {description}"
     # This kind of upgrade is non-breaking but if we want to automatically upgrade it,
     # then we should use the message store and old_names values instead of duplicating
     # MESSAGE_RENAMED= "{symbol} ({msgid}) was renamed"
@@ -27,11 +29,14 @@ class Condition(enum.Enum):
     MESSAGE_IS_NOT_DISABLED = "{symbol} ({msgid}) is not disabled"
     EXTENSION_IS_LOADED = "{extension} is loaded"
     EXTENSION_IS_NOT_LOADED = "{extension} is not loaded"
+    OPTION_IS_PRESENT = "{option} is present in configuration"
 
 
 class Information(NamedTuple):
-    msgid_or_symbol: str
-    extension: str | None
+    msgid_or_symbol: str | None = None
+    extension: str | None = None
+    option: list[str] | str | None = None
+    description: str | None = None
 
 
 class Solution(enum.Enum):
@@ -49,6 +54,8 @@ class Solution(enum.Enum):
     DISABLE_MESSAGE_IMPLICITLY = (
         "{symbol} ({msgid}) should be removed from the 'enable' option"
     )
+    REMOVE_OPTION = "Remove {option} from configuration"
+    REVIEW_OPTION = "Review and adjust or remove {option}: {description}"
 
 
 ConditionsToBeAffected = list[Condition]
@@ -71,6 +78,23 @@ class Solution(enum.Enum):
     extension="pylint.extensions.emptystring",
 )
 
+SUGGESTION_MODE_REMOVED = Information(
+    option="suggestion-mode",
+    description="This option is no longer used and should be removed",
+)
+
+INVALID_NAME_CONST_BEHAVIOR = Information(
+    option=["const-rgx", "const-naming-style"],
+    description="""\
+In 'invalid-name', module-level constants that are reassigned are now treated
+as variables and checked against ``--variable-rgx`` rather than ``--const-rgx``.
+Module-level lists, sets, and objects can pass against either regex.
+
+You may need to adjust this option to match your naming conventions.
+
+See the release notes for concrete examples: https://pylint.readthedocs.io/en/stable/whatsnew/4/4.0/index.html""",
+)
+
 CONFIGURATION_BREAKING_CHANGES: dict[str, list[BreakingChangeWithSolution]] = {
     "2.14.0": [
         (
@@ -94,4 +118,18 @@ class Solution(enum.Enum):
             [[Solution.REMOVE_EXTENSION, Solution.ENABLE_MESSAGE_EXPLICITLY]],
         ),
     ],
+    "4.0.0": [
+        (
+            BreakingChange.OPTION_REMOVED,
+            SUGGESTION_MODE_REMOVED,
+            [Condition.OPTION_IS_PRESENT],
+            [[Solution.REMOVE_OPTION]],
+        ),
+        (
+            BreakingChange.OPTION_BEHAVIOR_CHANGED,
+            INVALID_NAME_CONST_BEHAVIOR,
+            [],
+            [[Solution.REVIEW_OPTION]],
+        ),
+    ],
 }