Introduce process for increasing protocol version

We need to start using protocol version 6 as it introduces new
LiveObjects functionality.

The main problem to solve is: how do we make sure that ably-cocoa
doesn't force a protocol version on a plugin that can't handle that
version?

Here we propose a simple solution. It's a bit clunky, but to be honest
our whole plugin mechanism is a bit clunky so I think we can live with
this additional clunkiness.

One other problem of the solution given here — that is, doing major
plugin-api releases — is that if, in the future, we have further
plugins, then we'll have to do new releases of _all_ the plugins just
because we needed to bump plugin-support for one of them. I hope that by
the time we need to do further plugins we'll have moved to ably-swift
(with plugins in-repo) and we won't have to worry about this!

Resolves ably/ably-liveobjects-swift-plugin#107.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: lawrence-forooghian

README.md

@@ -10,3 +10,89 @@ Further documentation will be added in the future.
 ## Conventions
 
 - Methods whose names begin with `nosync_` must always be called on the client's internal queue.
+
+## Dependency setup
+
+The intention is that:
+
+- ably-cocoa's `Package.swift` declares a dependency on plugin-api
+- each plugin's `Package.swift` declares a dependency on plugin-api
+- each plugin's `Package.swift` also declares a direct dependency on ably-cocoa
+
+This means that:
+
+- a given version of the plugin is able to specify a _minimum_ version of ably-cocoa
+- a given version of ably-cocoa is expected to work with all plugin versions whose minimum it satisfies — i.e. ably-cocoa is _not_ able to specify a minimum version of a plugin
+
+The only way that ably-cocoa can exclude certain plugin versions is by creating a clash in the plugin-api dependency; we avoid using this mechanism where possible as it can cause confusing dependency resolution error messages for users, but reserve it, for example, when [introducing breaking Realtime protocol changes](#breaking-realtime-protocol-version-changes).
+
+## Playbook for making changes
+
+This section describes how to make some common changes that require changes to all three repositories (ably-cocoa, the plugin, and this repo).
+
+### Breaking Realtime protocol version changes
+
+In this section we describe how to make changes that require incrementing the [CSV2](https://sdk.ably.com/builds/ably/specification/main/features/#CSV2) protocol version number.
+
+The key outcome that we wish to achieve is the following:
+
+- a given version of ably-cocoa only needs to support a single protocol version
+- a given version of the plugin only needs to support a single protocol version
+
+— that is, we do not wish to try and implement negotiation of protocol version between ably-cocoa and the plugin.
+
+In order to do this, whenever we increment the CSV2 protocol number in such a way as could cause incompatibility with a plugin, this repo (plugin-api) will make a **breaking API change**, and thus **bump its major version**.
+
+#### Properties to replace
+
+The aforementioned breaking plugin-api change is implemented by replacing the two required protocol properties shown below with equivalents that refer to the new protocol version (e.g. when moving from v6 to v7, rename `usesLiveObjectsProtocolV6` to `usesLiveObjectsProtocolV7`, and similarly rename `compatibleWithProtocolV6` to `compatibleWithProtocolV7`). Note that only one property is needed in order to create a breaking API change, but we provide both so that both parties can check the other's conformance even if package dependencies are not configured correctly.
+
+The current properties are:
+
+In `APPluginAPIProtocol`:
+
+```
+/// Whether the SDK uses a protocol version which, as far as a LiveObjects
+/// plugin is concerned, is equivalent to protocol v6.
+///
+/// If the SDK uses a protocol version which is higher than 6 but whose
+/// breaking changes compared to v6 do not affect LiveObjects plugins, this
+/// property may still return `YES`.
+///
+/// This property **must** return `YES`. If you wish to introduce a protocol
+/// version change, see the "Breaking Realtime protocol version changes"
+/// section in the Readme.
+@property (nonatomic, readonly) BOOL usesLiveObjectsProtocolV6;
+```
+
+> [!NOTE]
+> The plugin should perform a runtime assertion that this property returns `YES`, to catch any scenario where package dependencies are incorrectly configured.
+
+In `APLiveObjectsInternalPluginProtocol`:
+
+```
+/// Whether this plugin is compatible with protocol v6.
+///
+/// If this property returns `YES`, it indicates that this plugin can be used
+/// with a version of ably-cocoa which uses protocol v6, or which uses a
+/// protocol version higher than v6 whose breaking changes compared to v6 do
+/// not affect LiveObjects plugins.
+///
+/// This property **must** return `YES`. If you wish to introduce a protocol
+/// version change, see the "Breaking Realtime protocol version changes"
+/// section in the Readme.
+@property (nonatomic, readonly) BOOL compatibleWithProtocolV6;
+```
+
+> [!NOTE]
+> ably-cocoa should perform a runtime assertion that this property returns `YES`, to catch any scenario where package dependencies are incorrectly configured.
+
+## Release process for breaking plugin-api changes
+
+The release process in such a scenario is not very smooth; there will be a brief period in which there exists a version of ably-cocoa without a plugin version that is compatible with it. During this window, a user who explicitly updates their `Package.swift` to require the new ably-cocoa version while also depending on the plugin will get a dependency resolution error. To minimise this window, have the plugin release PR reviewed and ready to merge before releasing ably-cocoa, so that the only remaining step is updating the ably-cocoa dependency from a commit pin to the released version tag.
+
+1. Prepare a release PR of plugin version `v_p`, with dependency on the new major version of plugin-api, but still pinned to an ably-cocoa commit. Do not release it.
+2. Prepare a release PR of ably-cocoa version `v_c`, with dependency on the new major version of plugin-api. Mention in the release message that it is compatible with version `v_p` of the plugin, which will be released shortly.
+3. Release ably-cocoa version `v_c`.
+4. Update the release PR of plugin version `v_p` to now point to ably-cocoa version `v_c`.
+5. Release plugin version `v_p`.

Sources/_AblyPluginSupportPrivate/include/APLiveObjectsPlugin.h

@@ -30,6 +30,18 @@ NS_SWIFT_NAME(LiveObjectsInternalPluginProtocol)
 NS_SWIFT_SENDABLE
 @protocol APLiveObjectsInternalPluginProtocol <NSObject>
 
+/// Whether this plugin is compatible with protocol v6.
+///
+/// If this property returns `YES`, it indicates that this plugin can be used
+/// with a version of ably-cocoa which uses protocol v6, or which uses a
+/// protocol version higher than v6 whose breaking changes compared to v6 do
+/// not affect LiveObjects plugins.
+///
+/// This property **must** return `YES`. If you wish to introduce a protocol
+/// version change, see the "Breaking Realtime protocol version changes"
+/// section in the Readme.
+@property (nonatomic, readonly) BOOL compatibleWithProtocolV6;
+
 /// ably-cocoa will call this method when initializing an `ARTRealtimeChannel` instance.
 ///
 /// The plugin can use this as an opportunity to perform any initial setup of LiveObjects functionality for this channel.

Sources/_AblyPluginSupportPrivate/include/APPluginAPI.h

@@ -17,6 +17,18 @@ NS_SWIFT_NAME(PluginAPIProtocol)
 NS_SWIFT_SENDABLE
 @protocol APPluginAPIProtocol
 
+/// Whether the SDK uses a protocol version which, as far as a LiveObjects
+/// plugin is concerned, is equivalent to protocol v6.
+///
+/// If the SDK uses a protocol version which is higher than 6 but whose
+/// breaking changes compared to v6 do not affect LiveObjects plugins, this
+/// property may still return `YES`.
+///
+/// This property **must** return `YES`. If you wish to introduce a protocol
+/// version change, see the "Breaking Realtime protocol version changes"
+/// section in the Readme.
+@property (nonatomic, readonly) BOOL usesLiveObjectsProtocolV6;
+
 /// Returns the internal objects that correspond to a public `ARTRealtimeChannel`.
 ///
 /// Plugins should, in general, not make use of `ARTRealtimeChannel` internally, and instead use `APRealtimeChannel`. This method is intended only to be used in plugin-authored extensions of `ARTRealtimeChannel`.