feat: deprecate releasing a realtime channel that isn't detached

[SimonWoolf]

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

channels.release(name) currently removes a realtime channel from the collection whatever its state. An attached channel is therefore dropped while it is still attached in the Ably service. From the next major version, releasing a channel that isn't INITIALIZED, DETACHED or FAILED will raise an AblyException with code 90011 (RTS4e). As RTS4b permits, this version keeps the current behaviour but logs a deprecation warning telling the user to await channel.detach() before calling release().

• Logs the deprecation warning, and updates the release() docstring.
• Rederives the channels collection UTS tests for RTS4c–e. The RTS4e test is gated as an RTS4b-permitted deviation and recorded in deviations.md.
• Adds unit tests checking the warning is logged for an attached channel and not for a detached one.

The next-major change is in #729. 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 an attached channel now logs a deprecation warning advising you to await detach() first. The channel is still removed from the collection without being detached.
  • Releasing a channel that is already detached or initialized does not log a deprecation warning.
  • Releasing a channel that is not in the collection remains a no-op.

• Documentation

  • Clarified the expected behavior for releasing channels in different states.

[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: 049c8637-e7ef-495b-8b4c-02d622c1ea62

📥 Commits

Reviewing files that changed from the base of the PR and between e195b3c and ebc2336.

📒 Files selected for processing (4)

• ably/realtime/channel.py
• test/unit/channels_release_test.py
• test/uts/deviations.md
• test/uts/realtime/unit/channels/channels_collection_test.py

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

Channels.release() now documents and logs a deprecation warning when called outside INITIALIZED, DETACHED, or FAILED. The changes add unit and realtime tests for channel release states, and update test deviation records and totals.

Changes

Channel Release

Layer / File(s)	Summary
Release behavior and unit tests ably/realtime/channel.py, test/unit/channels_release_test.py	release() warns when called outside INITIALIZED, DETACHED, or FAILED and removes a known channel. Unit tests check warning behavior for attached and detached channels, and verify removal.
Realtime release coverage test/uts/realtime/unit/channels/channels_collection_test.py, test/uts/deviations.md	Realtime tests cover release from multiple channel states. The attached-channel test expects error 90011 with status 400 and no detach or removal. Deviation records and test totals are updated.

Priority: ⬇️ Low

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

Change: Feature

Suggested reviewers: owenpearson

Merge Risk: ⚪ Minimal · up to ebc23

The change is mergeable after normal checks; releasing an attached channel remains permitted in this version and now warns callers to detach first.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 13.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 3 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 clearly describes the main change: deprecating release calls for realtime channels that are not detached.

Full details: Docstring Coverage

Explanation

Docstring coverage is 13.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 3 files. (1 skipped: 1 unsupported.)

• 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 checks the channel’s state,
Then notes the warning by the gate.
The detached path stays quiet and clear,
Test cases hop from state to state here.
The rabbit files its notes with care.}

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