Deprecate releasing a realtime channel that isn't detached (RTS4b)

[SimonWoolf]

Implements the RTS4b deprecation from spec 6.3.0 (ably/specification#557).

Spec 6.3.0 replaces RTS4a, where channels.release() implicitly detaches the channel, with RTS4e, where releasing a channel that isn't INITIALIZED, DETACHED or FAILED is an error (90011). This SDK keeps the current behaviour until the next major version but now logs a deprecation warning when release() is called on a channel in any other state. To avoid the warning, call channel.detach() and wait for it to complete before calling channels.release(name).

• Logs a warning in AblyRealtime.Channels.release for non-terminal states.
• Updates the release() docs (javadoc and the pubsub-adapter KDoc).
• Adds UTS-derived tests for RTS4c and RTS4d, and a test for the warning.

The behaviour change for the next major is in #1251. 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

• Behavior Changes
  • Releasing a realtime channel while it is attached or in a state other than initialized, detached, or failed still releases it and logs a deprecation warning.
  • Releasing a channel in these states is deprecated and is expected to throw an error in the next major version.
• Tests
  • Added coverage for releasing nonexistent, initialized, detached, and attached channels.

[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: 5c4e86a4-dc23-4b07-a640-c830ef8671c2

---

📥 Commits

Reviewing files that changed from the base of the PR and between 17b57f4 and 3462e23.

---

📒 Files selected for processing (1)

• lib/src/main/java/io/ably/lib/realtime/AblyRealtime.java

---

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

Channel release removes and marks the channel as released. It logs a deprecation warning for states other than INITIALIZED, DETACHED, or FAILED, then continues cleanup. Documentation describes the deprecation and planned error in the next major version. Tests cover release across channel states.

Changes

Channel release behavior

Layer / File(s)	Summary
Release warning and coverage lib/src/main/java/io/ably/lib/realtime/AblyRealtime.java, lib/src/test/kotlin/io/ably/lib/uts/unit/realtime/ChannelsCollectionTest.kt, pubsub-adapter/src/main/kotlin/com/ably/pubsub/Channels.kt	The release implementation removes and marks the channel as released, then warns for states other than INITIALIZED, DETACHED, or FAILED before continuing cleanup. Documentation describes the deprecation and planned error in the next major version. Tests cover nonexistent, initialized, detached, and attached channels.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Suggested reviewers: raphaelfakhri

Merge Risk: ⚪ Minimal · up to 3462e

Channel release continues its cleanup while warning for a captured state outside the permitted states. No material merge-blocking behavior is established.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the main change: deprecating release of a realtime channel while it is attached. It is concise and relevant to the changeset.
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.

---

---

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

---

🧪 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 watched the channels flow
And saw the warning softly glow
Released, detached, the tests all cheer
The next major change is drawing near
With tidy states, the paths are clear}

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

[Copilot]

🟢 Approval recommended

No unresolved blocking issues were identified.

0 open findings

What changed in this PR

Deprecates releasing realtime channels that are not in terminal states while preserving current behavior.

Changes:

• Adds deprecation warnings for non-terminal channel releases.
• Updates Java and Kotlin documentation.
• Adds release and warning tests.

File	Description
pubsub-adapter/​src/​main/​kotlin/​com/​ably/​pubsub/​Channels.kt	Updates release KDoc.
lib/​src/​test/​kotlin/​io/​ably/​lib/​uts/​unit/​realtime/​ChannelsCollectionTest.kt	Adds release behavior and warning tests.
lib/​src/​main/​java/​io/​ably/​lib/​realtime/​AblyRealtime.java	Adds deprecation warning logic.

🧠 Review effort: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sacOO7]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Already reviewed the last commit. Use @coderabbitai full review to rerun a review of the entire changeset.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.