docs: deprecate releasing a realtime channel that isn't detached (RTS4b)

[SimonWoolf]

Implements the documentation side of RTS4b from spec 6.3.0 (ably/specification#557) for the current major version. Spec 6.3.0 replaces RTS4a (release() implicitly detaches a channel that isn't INITIALIZED, DETACHED or FAILED) with RTS4e (release() fails with error 90011). SDKs may keep the old behaviour until their next major version, but must log a deprecation warning.

• Updates the RealtimeChannels.release / Channels.release docs to say that releasing a realtime channel that isn't INITIALIZED, DETACHED or FAILED is deprecated and will be an error in the next major version. They previously claimed, incorrectly, that the channel had to be in one of those states.
• The deprecation warning itself is logged by ably-java and ably-cocoa, which perform the release and know the channel's true state. RealtimeChannel.state on the Dart side is updated asynchronously from platform events, so a Dart-side check could warn spuriously. Users will see the warning once this plugin is bumped to the ably-java / ably-cocoa releases that include it.

The next-major change is in #610. Reference ably-js PRs: ably/ably-pubsub-js#2322 (deprecation) and ably/ably-pubsub-js#2323 (next major).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified that releasing a realtime channel outside the INITIALIZED, DETACHED, or FAILED states is deprecated. The documentation notes that this operation will throw an error in the next major version.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: d76c53f6-b30d-4ab9-a352-b73427349d09

📥 Commits

Reviewing files that changed from the base of the PR and between 1537db2 and 64974de.

📒 Files selected for processing (2)

• lib/src/common/src/channels.dart
• lib/src/platform/src/realtime/realtime_channels.dart

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

The release documentation in two files now describes releasing realtime channels outside the INITIALIZED, DETACHED, or FAILED states as deprecated. It says this will throw an error in the next major version.

Changes

Release documentation

Layer / File(s)	Summary
Document release-state guidance lib/src/common/src/channels.dart, lib/src/platform/src/realtime/realtime_channels.dart	Both release documentation comments describe releasing realtime channels outside the listed states as deprecated and say this will throw an error in the next major version.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 64974

This change clarifies release-state guidance without changing runtime behavior. No merge-blocking concern is apparent; it appears ready after normal checks.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title accurately identifies the documentation change and deprecation, but it is narrower than the change because releasing in INITIALIZED and FAILED is also allowed.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

_{A rabbit reads the release note,
Three states now guide the channel’s boat.
Release elsewhere, the docs now say,
Will bring an error on a future day.
I nibble clover, hop along,
And celebrate with one small song.}

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