docs: update migration guide and changelog for v3.0.0 release

- Added instructions for updating to v3.0.0 in `UPDATING.md`
- Detailed breaking changes and enhancements in `CHANGELOG.md`

Author: ttypic

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Change Log
 
+## [v3.0.0](https://github.com/ably/ably-python/tree/v3.0.0)
+
+[Full Changelog](https://github.com/ably/ably-python/compare/v2.1.3...v3.0.0)
+
+### What's Changed
+
+- Added realtime publish support for publishing messages to channels over the realtime connection [#648](https://github.com/ably/ably-python/pull/648)
+- Added realtime presence support, allowing clients to track presence on channels [#651](https://github.com/ably/ably-python/pull/651)
+- Added mutable messages API with support for editing, deleting, and appending to messages [#660](https://github.com/ably/ably-python/pull/660), [#659](https://github.com/ably/ably-python/pull/659)
+- Added publish results containing serial of published messages [#660](https://github.com/ably/ably-python/pull/660), [#659](https://github.com/ably/ably-python/pull/659)
+
+### Breaking change
+
+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:
+
+- Realtime publish now uses WebSocket connection instead of REST
+- `ably.realtime.realtime_channel` module renamed to `ably.realtime.channel`
+- `ChannelOptions` moved to `ably.types.channeloptions`
+- REST publish returns publish result with message serials instead of Response object
+
+For detailed migration instructions, please refer to the [Upgrading Guide](UPDATING.md).
+
 ## [v2.1.3](https://github.com/ably/ably-python/tree/v2.1.3)
 
 [Full Changelog](https://github.com/ably/ably-python/compare/v2.1.2...v2.1.3)

UPDATING.md

@@ -1,5 +1,67 @@
 # Upgrade / Migration Guide
 
+## 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:
+
+  - Realtime publish now uses WebSocket connection instead of REST
+  - `ably.realtime.realtime_channel` module renamed to `ably.realtime.channel`
+  - `ChannelOptions` moved to `ably.types.channeloptions`
+  - REST publish returns publish result with message serials instead of Response object
+
+### Realtime publish now uses WebSocket
+
+In previous versions, publishing messages on a realtime channel would use the REST API. In version 3.0.0, realtime channels now publish messages over the WebSocket connection, which is more efficient and provides better consistency.
+
+This change is mostly transparent to users, but you should be aware that:
+- Messages are now published through the realtime connection
+- You will receive publish results containing message serials
+- The behavior is now consistent with other Ably SDKs
+
+### Module rename: `ably.realtime.realtime_channel` to `ably.realtime.channel`
+
+If you were importing from `ably.realtime.realtime_channel`, you will need to update your imports:
+
+Example 2.x code:
+```python
+from ably.realtime.realtime_channel import RealtimeChannel
+```
+
+Example 3.0.0 code:
+```python
+from ably.realtime.channel import RealtimeChannel
+```
+
+### `ChannelOptions` moved to `ably.types.channeloptions`
+
+The `ChannelOptions` class has been moved to a new location for better organization.
+
+Example 2.x code:
+```python
+from ably.realtime.realtime_channel import ChannelOptions
+```
+
+Example 3.0.0 code:
+```python
+from ably.types.channeloptions import ChannelOptions
+```
+
+### REST publish returns publish result with serials
+
+The REST `publish` method now returns a publish result object containing the message serial(s) instead of a raw Response object with `status_code`.
+
+Example 2.x code:
+```python
+response = await channel.publish('event', 'message')
+print(response.status_code)  # 201
+```
+
+Example 3.0.0 code:
+```python
+result = await channel.publish('event', 'message')
+print(result.serials)  # message serials
+```
+
 ## Version 1.2.x to 2.x
 
 The 2.0 version of ably-python introduces our first Python realtime client. For guidance on how to use the realtime client, refer to the usage examples in the [README](./README.md).