[improve] [doc] Add compatibility reminders for retry queues

[poorbarcode]

This PR fixes apache/pulsar#20612

The default naming rule of Retry topic is {tenant}/{namespaces}/{topic}-{sub}-RETRY, see: https://pulsar.apache.org/docs/3.0.x/concepts-messaging/#retry-letter-topic

The rule before version 2.8 was {tenant}/{namespaces}/{sub}-RETRY, and if there is a ZK node /admin/partitioned-topics/{namespace}-RETRY, Pulsar will still use the rule {tenant}/{namespaces}/{sub}-RETRY even if the version of Pulsar is larger than 2.8. This part of the explanation is not reflected in the documentation.

Related PR

• #6449 Support Consumers Set Custom Retry Delay
• #10129 fix the default retry letter and dead letter topic name

• doc
• doc-required
• doc-not-needed
• doc-complete

[Anonymitaet]

@gaoran10
Could you please help review this PR from a technical perspective? Then writers will review it from a technical writing side. Thank you!

[Anonymitaet]

ping @gaoran10 to review, tia!

[Anonymitaet]

ping @gaoran10 to review, tia!

[xiaogang-sn]

If manually specifying the name of retry letter topic or dead letter topic can also achieve the goal we can mention it along the changes as well.

It may also be worthy noting that using <subscriptionname>-RETRY as topic name may cause trouble when multiple topics in the same namespace having the subscriptions with the same name.

[poorbarcode]

@xiaogang-sn

If manually specifying the name of retry letter topic or dead letter topic can also achieve the goal we can mention it along the changes as well.

Correct, the following section explains this solution.

It may also be worthy noting that using -RETRY as topic name may cause trouble when multiple topics in the same namespace having the subscriptions with the same name.

Correct, so in 2.8.x, the format rule was changed to {topic}-{sub}-RETRY

[xiaogang-sn]

I would suggest to add the consequence in brief if continuing using <subscriptionname>-RETRYas retry topic name or add a reference link to the relevant issue/pr. The rest looks good to me.

[poorbarcode]

@xiaogang-sn

I would suggest to add the consequence in brief if continuing using -RETRYas retry topic name or add a reference link to the relevant issue/pr. The rest looks good to me.

Done

[Anonymitaet]

Suggested change

	Note: In versions `2.6.x` and `2.7.x`, the default retry letter topic uses this format is `<subscriptionname>-RETRY`.
	If you are upgrading from version `2.6.x~2.7.x` to version `2.8.x` or greater, then you need to manually delete
	the historical retry letter topics and retry letter partitioned topics. Otherwise, Pulsar will continue to use the
	original topics, which were formatted with `<subscriptionname>-RETRY`. Rule `<subscriptionname>-RETRY` should be avoided
	to use, because if multiple topics under the same namespace have the same subscription, the retry message topic names
	for multiple topics will be the same, resulting in mutual consumption.
	:::note
	- For Pulsar 2.6.x and 2.7.x, the default retry letter topic uses the format of `<subscriptionname>-RETRY`. If you upgrade from 2.6.x~2.7.x to 2.8.x or later, you need to delete historical retry letter topics and retry letter partitioned topics. Otherwise, Pulsar continues to use original topics, which are formatted with `<subscriptionname>-RETRY`.
	- It is not recommended to use `<subscriptionname>-RETRY` because if multiple topics under the same namespace have the same subscription, then retry message topic names for multiple topics might be the same, which will result in mutual consumptions.
	:::

[poorbarcode]

Fixed

[poorbarcode]

[gaoran10]

LGTM