docs: pipeline: outputs: forward: explicit warning for v5.0.4 default config param change

  - document v5.0.4 default change and Fluentd incompatibility for
    retain_metadata_in_forward_mode
  - fixed classic config casing in example.

  Applies to fluent/fluent-bit#11877

Signed-off-by: Eric D. Schabell <eric@schabell.org>

Author: eschabell

installation/upgrade-notes.md

@@ -36,11 +36,11 @@ If you tune `http`, `splunk`, `elasticsearch`, `opentelemetry`, or `prometheus_r
 
 Input plugins that support TLS now also support `tls.verify_client_cert`. Enable this option to require and validate the client certificate presented by the sender.
 
-If you terminate TLS directly in Fluent Bit and need mutual TLS (`mTLS`), add `tls.verify_client_cert on` together with the usual `tls.crt_file` and `tls.key_file` settings.
+If you end TLS directly in Fluent Bit and need mutual TLS (`mTLS`), add `tls.verify_client_cert on` together with the usual `tls.crt_file` and `tls.key_file` settings.
 
 ### New internal logs input
 
-Fluent Bit `v5.0` adds the `fluentbit_logs` input plugin, which mirrors Fluent Bit's own internal log stream back into the data pipeline as structured log records.
+Fluent Bit `v5.0` adds the `fluentbit_logs` input plugin, which mirrors the Fluent Bit internal log stream back into the data pipeline as structured log records.
 
 Use this input if you want to forward Fluent Bit diagnostics to another destination, filter them, or store them alongside the rest of your telemetry.
 
@@ -65,7 +65,7 @@ If you previously handled authentication outside Fluent Bit for these cases, rev
 
 Starting in Fluent Bit v5.0.4, the `forward` output plugin's `retain_metadata_in_forward_mode` option defaults to `true` (previously `false`). When `true`, Fluent Bit embeds event metadata into the Forward protocol payload using the extended MessagePack format.
 
-Fluentd receivers do not understand this format and will reject events with a warning similar to:
+Fluentd receivers don't understand this format and will reject events with a warning similar to:
 
 ```text
 [input1] skip invalid event: host="..." tag="..." time=[..., {}] record={...}
@@ -92,7 +92,7 @@ pipeline:
     Match   *
     Host    fluentd-host
     Port    24224
-    retain_metadata_in_forward_mode false
+    Retain_Metadata_In_Forward_Mode false
 ```
 {% endtab %}
 {% endtabs %}

pipeline/outputs/forward.md

@@ -29,7 +29,7 @@ The following parameters are mandatory for both Forward and Secure Forward modes
 | `require_ack_response` | Send the `chunk` option and wait for an `ack` response from the server. This enables at-least-once delivery and lets the receiving server control traffic rate. Requires Fluentd `v0.14.0` or later. | `false` |
 | `compress` | Set to `gzip` to enable gzip compression. Incompatible with `time_as_integer true` and tags set dynamically using the [Rewrite Tag](../filters/rewrite-tag.md) filter. Requires Fluentd server `v0.14.7` or later. | _none_ |
 | `fluentd_compat` | Send metrics and traces using a Fluentd-compatible format. | `false` |
-| `retain_metadata_in_forward_mode` | Retain metadata when operating in forward mode. | `true` |
+| `retain_metadata_in_forward_mode` | Retain metadata when operating in forward mode. **Changed to `true` in v5.0.4.** Set to `false` when sending to Fluentd. Fluentd doesn't support the extended metadata format and will log `[input1] skip invalid event` and drop all records. | `true` |
 | `add_option` | Add an extra Forward protocol option. This is an advanced setting and can be specified multiple times. Enabling it also enables `send_options`. | _none_ |
 | `workers` | The number of [workers](../../administration/multithreading.md#outputs) to perform flush operations for this output. | `2` |