pubsub: raise 90011 when releasing a realtime channel that isn't detached

UPDATING.md

@@ -93,6 +93,25 @@ async def subscribe(client: PubSubRealtimeClient, name: str) -> None: ...
 def publish_blocking(client: PubSubHttpClientSync, name: str) -> None: ...
 ```
 
+### Releasing a realtime channel requires it to be detached
+
+`channels.release(name)` on a realtime client now raises an `AblyException` with code 90011
+if the channel is in any state other than `INITIALIZED`, `DETACHED` or `FAILED`, and leaves the
+channel as it was. 3.x removed the channel from the collection whatever its state, which could
+leave it attached in the Ably service, and later 3.x releases log a deprecation warning when
+they do so. Detach the channel, and wait for that to complete, before releasing it:
+
+Example 3.x code:
+```python
+realtime.channels.release('my-channel')
+```
+
+Example 4.0.0 code:
+```python
+await pubsub_realtime_client.channels.get('my-channel').detach()
+pubsub_realtime_client.channels.release('my-channel')
+```
+
 ## Version 2.x to 3.0.0
 
 The 3.0.0 version of ably-python introduces several breaking changes to improve the realtime experience and align the API with the Ably specification. These include:

ably/pubsub/realtime/channel.py

@@ -1015,16 +1015,33 @@ def release(self, name: str) -> None:
         """Releases a RealtimeChannel object, deleting it, and enabling it to be garbage collected
 
         It also removes any listeners associated with the channel.
-        To release a channel, the channel state must be INITIALIZED, DETACHED, or FAILED.
-
+        A realtime channel can only be released when it is in the INITIALIZED, DETACHED, or FAILED state.
 
         Parameters
         ----------
         name: str
             Channel name
+
+        Raises
+        ------
+        AblyException
+            With code 90011 if the channel is in any other state. Await channel.detach() before
+            calling release().
         """
+        # RTS4c
         if name not in self.__all:
             return
+        channel = self.__all[name]
+        # RTS4e
+        if channel.state not in (ChannelState.INITIALIZED, ChannelState.DETACHED, ChannelState.FAILED):
+            raise AblyException(
+                'Can only release a channel in a state where there is no possibility of further updates '
+                'from the server being received (initialized, detached, or failed). The current state is '
+                f'{channel.state.value}',
+                400,
+                90011,
+            )
+        # RTS4d
         del self.__all[name]
 
     def _on_channel_message(self, msg: dict) -> None: