Add doc to explain how to migrate to the new BroadcastLogger:

- This should make it easier for apps or libraries that were
  previously relying on the private API.
  Also took the opportunity to tweak the doc of the BroadcastLogger
  to mention what happens when calling a non-standard method.

  Fix #49494

activesupport/lib/active_support/broadcast_logger.rb

@@ -51,6 +51,26 @@ module ActiveSupport
   #
   #   broadcast = BroadcastLogger.new
   #   broadcast.info("Hello world") # The log message will appear nowhere.
+  #
+  # If you are adding a custom logger with custom methods to the broadcast,
+  # the `BroadcastLogger` will proxy them and return the raw value, or an array
+  # of raw values, depending on how many loggers in the broadcasts responded to
+  # the method:
+  #
+  #   class MyLogger < ::Logger
+  #     def loggable?
+  #       true
+  #     end
+  #   end
+  #
+  #   logger = BroadcastLogger.new
+  #   logger.loggable? # => A NoMethodError exception is raised because no loggers in the broadcasts could respond.
+  #
+  #   logger.broadcast_to(MyLogger.new(STDOUT))
+  #   logger.loggable? # => true
+  #   logger.broadcast_to(MyLogger.new(STDOUT))
+  #   puts logger.broadcasts # => [MyLogger, MyLogger]
+  #   logger.loggable? # [true, true]
   class BroadcastLogger
     include ActiveSupport::LoggerSilence
 

guides/source/upgrading_ruby_on_rails.md

@@ -281,6 +281,38 @@ ActiveSupport.on_load :action_view_test_case do
 end
 ```
 
+### `Rails.logger` now returns an `ActiveSupport::BroadcastLogger` instance
+
+The `ActiveSupport::BroadcastLogger` class is a new logger that allows to broadcast logs to different sinks (STDOUT, a log file...) in an easy way.
+
+The API to broadcast logs (using the `ActiveSupport::Logger.broadcast` method) was removed and was previously private.
+If your application or library was relying on this API, you need to make the following changes:
+
+```ruby
+logger = Logger.new("some_file.log")
+
+# Before
+
+Rails.logger.extend(ActiveSupport::Logger.broadcast(logger))
+
+# After
+
+Rails.logger.broadcast_to(logger)
+```
+
+If your application had configured a custom logger, `Rails.logger` will wrap and proxy all methods to it. No changes on your side are required to make it work.
+
+If you need to access your custom logger instance, you can do so using the `broadcasts` method:
+
+```ruby
+# config/application.rb
+config.logger = MyLogger.new
+
+# Anywhere in your application
+puts Rails.logger.class #=> BroadcastLogger
+puts Rails.logger.broadcasts #=> [MyLogger]
+```
+
 [assert_match]: https://docs.seattlerb.org/minitest/Minitest/Assertions.html#method-i-assert_match
 
 Upgrading from Rails 6.1 to Rails 7.0