Feature/pub 1676 message annotations

[mschristensen]

Description

Adds docs for the message annotations feature to the Messages section of the Pub/Sub product docs.

Includes:

• How to enable annotations via a channel rule (work to enable this via website is in flight)
• Description of annotation type specifiers the different summarization methods and their semantics
• How to publish and delete annotations
• How to subscribe to annotation summaries and individual annotation events

Not ready to merge yet until we are ready to make the release but opening as draft now for early review.

Checklist

• Commits have been rebased.
• Linting has been run against the changed file(s).
• The PR adheres to the writing style guide and contribution guide.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/PUB-1676-message-annotations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[SimonWoolf]

Couple comments & suggestions but generally looks good 👍
will leave it to the docs team to approve.

[mschristensen]

@m-hulbert for some reason the left nav menu gets squished when the content is too wide, despite the fact that it seems to wrap okay

[mschristensen]

In 9582fcf I have added the error codes used by message annotations, which have been updated in ably/ably-common#307

And aligned in realtime in: https://github.com/ably/realtime/pull/7514

We need to decide on the name used for the channel rule in the website and can align the error codes, error messages used in realtime and the docs here accordingly.

[mschristensen]

In 66a92ed I have renamed the "Mutable messages" channel rule to "Advanced message features" per ADR-144 (pending decision) and included the appropriate caveats for features that are not yet supported on mutable messages enabled channels.

[m-hulbert]

Thanks Mike, this is comprehensive in terms of content - I just think shuffling the content around might help in understanding it a little quicker.

I know I've made various suggestions throughout, but in hindsight I wonder if the entire page should speak solely in terms of message summaries considering that is what we recommend. Then we have an independent section at the end that explains how/why you can subscribe to individual events. Otherwise it becomes quite complex to explain both instances everywhere. This would make some of my comments obsolete, but let me know what you think.

Also, the content squish is a regression in the MDX implementation which I've logged with the web team. It's related to codeblock scrolling/wrapping of long lines where we've added line numbering.

[m-hulbert]

I wonder if this should be part of the intro section, but more importantly clearly state that annotation (summaries) use the same listener as regular messages on the channel. WDYT?

[m-hulbert]

I'd pull this up into the intro of the section and out of the aside.

[SimonWoolf]

I'm rewriting this para. "More reliable" is not right (receiving raw annotations is perfectly reliable)

[mschristensen]

Agree with Simon's comment, otherwise this LGTM @m-hulbert, reads nicely, thanks :)

[m-hulbert]

Made the update to the modes. I also updated the channel rule with the latest terminology, and rebased to fix the issue with the page widths, so it should be readable in the review app now.

[SimonWoolf]

I've rebased this on main (somewhat painfully) and updated it for protocol v4. (Our docs will just unconditionally use protocol v4 message docs for annotations and updates, since by the time we release those features experimentally all 3 sdks which had support for them will be updated to v4).

I didn't keep the previous commit structure; there were a lot of fixup commits that didn't cleanly apply to the commit they were fixing up given other ones inbetween. I squashed it down to one commit nominally written by @mschristensen , and added my changes as a new commit after that.

[m-hulbert]

LGTM - thanks for taking the hit on the rebase @SimonWoolf