{Core} Support core bc announcing and Optimize conditional bc usage (#31060)

* Initialize Conditional BC in core

* Support Register BC in core

* Specify the name as login

* Update Conditional BC doc

* Fix indent in doc

* Fix file name issue

* Revert BC announcement in core

* Fix style

* Support Breaking Changes announced in core

* Fix Conditional breaking change style

* Add a custom message to deprecate info in Breaking Change method

Author: ReaNAiveD

doc/how_to_introduce_breaking_changes.md

@@ -274,26 +274,42 @@ register_other_breaking_change('bar foo', 'During May 2024, another Breaking Cha
 
 **Conditional Breaking Change**
 
-To enhance flexibility, the CLI supports using a designated tag to specify a Breaking Change Pre-announcement. This method avoids reliance on the default automatic warning display and allows the warning to be shown whenever `print_manual_breaking_change` is called.
+To enhance flexibility, the CLI supports using a designated tag to specify a Breaking Change Pre-announcement. This method avoids reliance on the default automatic warning display and allows the warning to be shown whenever `print_conditional_breaking_change` is called.
 
 **Note:** We strongly recommend using this method to display breaking change warnings under specific conditions instead of using `logger.warning` directly. This approach enables centralized documentation of breaking changes and assists in automating customer notifications.
 
+* Register
+  * `tag`: The tag of the conditional breaking change. Use the same tag to print.
+  * `breaking_change`: Breaking change item to be announced. This should be an instance of `BreakingChange` subclass or a string. You should provide `command_name` when it is a string.
+  * `command_name`: Used only when input str as a breaking change. This would restrict the scope of breaking change tag.
+* Print
+  * `cli_ctx`: Context object. Pass this as `None` only when specifying `command_name` manually.
+  * `tag` : The tag of the conditional breaking change. Use the same tag to print.
+  * `custom_logger`: The logger used to print the warning.
+  * `command_name`: Used only when `cli_ctx` is `None`.
+
 ```python
 # src/azure-cli/azure/cli/command_modules/vm/_breaking_change.py
-from azure.cli.core.breaking_change import AzCLIOtherChange, register_conditional_breaking_change
+from azure.cli.core.breaking_change import register_conditional_breaking_change, AzCLIOtherChange
 
 register_conditional_breaking_change(tag='SpecialBreakingChangeA', breaking_change=AzCLIOtherChange(
-  'vm create', 'This is special Breaking Change Warning A. This breaking change is happend in "vm create" command.'))
-register_conditional_breaking_change(tag='SpecialBreakingChangeB', breaking_change=AzCLIOtherChange(
-  'vm', 'This is special Breaking Change Warning B. This breaking change is happend in "vm" command group.'))
+    'vm create', 'This is special Breaking Change Warning A. This breaking change is happend in "vm create" command.'))
+register_conditional_breaking_change(
+    tag='SpecialBreakingChangeB',
+    breaking_change='This is special Breaking Change Warning B. This breaking change is happend in "vm" command group.',
+    command_name='vm'
+)
 
 
 # src/azure-cli/azure/cli/command_modules/vm/custom.py
 def create_vm(cmd, vm_name, **):
-  from azure.cli.core.breaking_change import print_conditional_breaking_change
-  if some_condition:
-    print_conditional_breaking_change(cmd.cli_ctx, tag='SpecialBreakingChangeA', custom_logger=logger)
-    print_conditional_breaking_change(cmd.cli_ctx, tag='SpecialBreakingChangeB', custom_logger=logger)
+    from azure.cli.core.breaking_change import print_conditional_breaking_change
+    if some_condition:
+        print_conditional_breaking_change(cmd.cli_ctx, tag='SpecialBreakingChangeA', custom_logger=logger)
+        print_conditional_breaking_change(cmd.cli_ctx, tag='SpecialBreakingChangeB', custom_logger=logger)
+
+# This is special Breaking Change Warning A. This breaking change is happend in "vm create" command.
+# This is special Breaking Change Warning B. This breaking change is happend in "vm" command group.
 ```
 
 This way, the pre-announcement wouldn't be displayed unless running into the branch, but still could be published in the [Azure CLI Breaking Changes]() article.

src/azure-cli-core/azure/cli/core/__init__.py

@@ -220,7 +220,8 @@ def load_command_table(self, args):
             _load_module_command_loader, _load_extension_command_loader, BLOCKED_MODS, ExtensionCommandSource)
         from azure.cli.core.extension import (
             get_extensions, get_extension_path, get_extension_modname)
-        from azure.cli.core.breaking_change import (import_module_breaking_changes, import_extension_breaking_changes)
+        from azure.cli.core.breaking_change import (
+            import_core_breaking_changes, import_module_breaking_changes, import_extension_breaking_changes)
 
         def _update_command_table_from_modules(args, command_modules=None):
             """Loads command tables from modules and merge into the main command table.
@@ -416,6 +417,9 @@ def _get_extension_suppressions(mod_loaders):
         self.command_group_table.clear()
         self.command_table.clear()
 
+        # Import announced breaking changes in azure.cli.core._breaking_change.py
+        import_core_breaking_changes()
+
         command_index = None
         # Set fallback=False to turn off command index in case of regression
         use_command_index = self.cli_ctx.config.getboolean('core', 'use_command_index', fallback=True)

src/azure-cli-core/azure/cli/core/breaking_change.py

@@ -5,6 +5,7 @@
 import abc
 import argparse
 import re
+import sys
 from collections import defaultdict
 
 from knack.log import get_logger
@@ -270,6 +271,8 @@ def register(self, cli_ctx):
             command_group = cli_ctx.invocation.commands_loader.command_group_table[self.command_name]
             if not command_group:
                 loader = self.find_suitable_command_loader(cli_ctx)
+                if not loader:
+                    return
                 command_group = loader.command_group(self.command_name)
                 cli_ctx.invocation.commands_loader.command_group_table[self.command_name] = command_group
             if command_group:
@@ -314,8 +317,9 @@ def _register_option_deprecate(self, cli_ctx, arguments, option_name):
 
 
 class AzCLIDeprecate(BreakingChange):
-    def __init__(self, cmd, arg=None, target_version=NextBreakingChangeWindow(), **kwargs):
+    def __init__(self, cmd, arg=None, target_version=NextBreakingChangeWindow(), message=None, **kwargs):
         super().__init__(cmd, arg, None, target_version)
+        self._message = message
         self.kwargs = kwargs
 
     @staticmethod
@@ -333,8 +337,8 @@ def _build_message(object_type, target, target_version, redirect):
 
     @property
     def message(self):
-        return self._build_message(self.kwargs.get('object_type'), self.target, self.target_version,
-                                   self.kwargs.get('redirect'))
+        return self._message or self._build_message(self.kwargs.get('object_type'), self.target, self.target_version,
+                                                    self.kwargs.get('redirect'))
 
     def to_tag(self, cli_ctx, **kwargs):
         if self.args:
@@ -345,7 +349,7 @@ def to_tag(self, cli_ctx, **kwargs):
             object_type = 'command'
         tag_kwargs = {
             'object_type': object_type,
-            'message_func': lambda depr: self._build_message(
+            'message_func': lambda depr: self._message or self._build_message(
                 depr.object_type, depr.target, self.target_version, depr.redirect),
             'target': self.target
         }
@@ -530,6 +534,14 @@ def message(self):
 upcoming_breaking_changes = defaultdict(lambda: [])
 
 
+def import_core_breaking_changes():
+    try:
+        from importlib import import_module
+        import_module('azure.cli.core._breaking_change')
+    except ImportError:
+        pass
+
+
 def import_module_breaking_changes(mod):
     try:
         from importlib import import_module
@@ -560,8 +572,8 @@ def update_breaking_change_info(cli_ctx, **kwargs):  # pylint: disable=unused-ar
     cli_ctx.register_event(events.EVENT_INVOKER_POST_CMD_TBL_CREATE, update_breaking_change_info)
 
 
-def register_deprecate_info(command_name, arg=None, target_version=NextBreakingChangeWindow(), **kwargs):
-    upcoming_breaking_changes[command_name].append(AzCLIDeprecate(command_name, arg, target_version, **kwargs))
+def register_deprecate_info(command_name, arg=None, target_version=NextBreakingChangeWindow(), message=None, **kwargs):
+    upcoming_breaking_changes[command_name].append(AzCLIDeprecate(command_name, arg, target_version, message, **kwargs))
 
 
 def register_output_breaking_change(command_name, description, target_version=NextBreakingChangeWindow(), guide=None,
@@ -592,30 +604,60 @@ def register_other_breaking_change(command_name, message, arg=None, target_versi
 
 
 def register_command_group_deprecate(command_group, redirect=None, hide=None,
-                                     target_version=NextBreakingChangeWindow(), **kwargs):
-    register_deprecate_info(command_group, redirect=redirect, hide=hide, target_version=target_version, **kwargs)
+                                     target_version=NextBreakingChangeWindow(), message=None, **kwargs):
+    register_deprecate_info(command_group, redirect=redirect, hide=hide, target_version=target_version,
+                            message=message, **kwargs)
 
 
 def register_command_deprecate(command, redirect=None, hide=None,
-                               target_version=NextBreakingChangeWindow(), **kwargs):
-    register_deprecate_info(command, redirect=redirect, hide=hide, target_version=target_version, **kwargs)
+                               target_version=NextBreakingChangeWindow(), message=None, **kwargs):
+    register_deprecate_info(command, redirect=redirect, hide=hide, target_version=target_version,
+                            message=message, **kwargs)
 
 
 def register_argument_deprecate(command, argument, redirect=None, hide=None,
-                                target_version=NextBreakingChangeWindow(), **kwargs):
-    register_deprecate_info(command, argument, redirect=redirect, hide=hide, target_version=target_version, **kwargs)
-
-
-def register_conditional_breaking_change(tag, breaking_change):
-    upcoming_breaking_changes[breaking_change.command_name + '.' + tag].append(breaking_change)
-
-
-def print_conditional_breaking_change(cli_ctx, tag, custom_logger=None):
-    command = cli_ctx.invocation.commands_loader.command_name
-    custom_logger = custom_logger or logger
+                                target_version=NextBreakingChangeWindow(), message=None, **kwargs):
+    register_deprecate_info(command, argument, redirect=redirect, hide=hide, target_version=target_version,
+                            message=message, **kwargs)
+
+
+def register_conditional_breaking_change(tag, breaking_change, *, command_name=None):
+    if command_name and command_name.startswith('az '):
+        command_name = command_name[3:].strip()
+    if isinstance(breaking_change, BreakingChange):
+        command_name = command_name or breaking_change.command_name
+        upcoming_breaking_changes[command_name + '.' + tag].append(breaking_change)
+    elif isinstance(breaking_change, str):
+        command_name = command_name or ''
+        upcoming_breaking_changes[command_name + '.' + tag].append(AzCLIOtherChange(
+            cmd=command_name,
+            message=breaking_change,
+        ))
+
+
+def print_conditional_breaking_change(cli_ctx, tag, *, custom_logger=None, command_name=None):
+    """
+    Print a breaking change warning message manually.
+    :param cli_ctx: By default, retrieve the command name from cli_ctx.
+    :param tag: Use the tag to distinguish different warning messages to be printed in the same command.
+    Please note, all breaking change items with the same tag from the parent command group will also be printed.
+    :param custom_logger: Use a custom logger to replace the logger in azure.cli.core.breaking_change.
+    :param command_name: Specify the command name if not pass in the cli_ctx
+    """
+    command = cli_ctx.invocation.commands_loader.command_name if cli_ctx else command_name
+    command = command or ''
+    tag_suffix = '.' + tag if tag is not None else ''
 
     command_comps = command.split()
     while command_comps:
-        for breaking_change in upcoming_breaking_changes.get(' '.join(command_comps) + '.' + tag, []):
-            custom_logger.warning(breaking_change.message)
+        for breaking_change in upcoming_breaking_changes.get(' '.join(command_comps) + tag_suffix, []):
+            if custom_logger:
+                custom_logger.warning(breaking_change.message)
+            else:
+                print(breaking_change.message, file=sys.stderr)
         del command_comps[-1]
+    for breaking_change in upcoming_breaking_changes.get(tag_suffix, []):
+        if custom_logger:
+            custom_logger.warning(breaking_change.message)
+        else:
+            print(breaking_change.message, file=sys.stderr)

src/azure-cli-core/azure/cli/core/commands/__init__.py

@@ -830,6 +830,9 @@ def _resolve_preview_and_deprecation_warnings(self, cmd, parsed_args):
                 experimentals.append(ImplicitExperimentalItem(cli_ctx=self.cli_ctx, **experimental_kwargs))
 
         if not self.cli_ctx.only_show_errors:
+            from azure.cli.core.breaking_change import upcoming_breaking_changes
+            for bc in upcoming_breaking_changes.get('', []):
+                print(bc.message, file=sys.stderr)
             for d in deprecations:
                 print(d.message, file=sys.stderr)
             for p in previews: