Merge pull request #49518 from Edouard-chin/ec-logger-doc

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

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

@@ -276,6 +276,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