In this repository the main branch contains the latest development version of the Ably SDK. All development (bug fixing, feature implementation, etc.) is done against the main branch, which you should branch from whenever you'd like to make modifications. Here's the steps to follow when contributing to this repository.
- Fork it
- Install gems:
bundle install - Setup or update your machine by running
make update - Create your feature branch from
main(git checkout main && git checkout -b my-new-feature-branch) - Commit your changes (
git commit -am 'Add some feature') - Ensure you have added suitable tests and the test suite is passing
- Push to the branch (
git push origin my-new-feature-branch) - Create a new Pull Request
Releases of the Ably SDK built by the sources in this repository are tagged with their semantic version numbers.
When you first clone the repository then you will need to run make update in order to
bring in the Git submodules.
Code can then be modified, built and tested by loading Ably.xcworkspace in your
Xcode IDE. The workspace contains the Swift package and nothing else, so its ably-pubsub-cocoa scheme —
declared in .swiftpm/xcode/xcshareddata/xcschemes — builds and tests the same targets swift build
and swift test do.
Dependencies are declared in Package.swift and resolved by Swift Package Manager.
The steps below are for the AblyPubSubDevice target, which is the whole SDK and whose sources live in Source/.
These are the header files that form the public interface of the SDK.
- Put
.hfile in directorySource/include/AblyPubSubDevice. - Add
#importto one of the following umbrella header files:Source/include/AblyPubSubDevice/AblyPublic.hif the API contained in this header is intended for general use.Source/include/AblyPubSubDevice/AblyInternal.hif the API contained in this header is intended for use only by Ably-authored SDKs and should not be included in the Jazzy-generated documentation.
These are the header files that form the internal interface of the SDK.
- Put
.hfile in directorySource/PrivateHeaders/Ably. - Add
headerdeclaration to thePrivatemodule in the module mapSource/include/module.modulemap.
- Put
.mfile in directorySource.
SwiftPM globs the AblyPubSubDevice target's directory, so none of these steps involves editing
Package.swift.
To run tests, do any of the following:
- use the Xcode UI to run on any platform
- run
swift testto run on your Mac - run
make test_[iOS|tvOS|macOS]to run on any platform
The make test_* commands are used by CI and expect you to have a simulator device of a specific model and OS version. See Fastfile for these values. If you don't have a matching simulator, you can create one using simctl. For example, xcrun simctl create "iPhone 12 (14.4)" "iPhone 12" "com.apple.CoreSimulator.SimRuntime.iOS-14-4".
swift test builds and runs every test target in the package:
| Target | Path | Contents |
|---|---|---|
AblyTests |
Test/AblyTests |
Swift tests for the SDK |
AblyTestsObjC |
Test/AblyTestsObjC |
Objective-C tests for the SDK |
UTS |
Test/UTS |
Universal Test Suite, derived from the language-neutral specs in the specification repository — including the ported LiveObjects objects unit specs under unit/objects/. Its objects suites link AblyLiveObjects — see Supported OS versions |
AblyLiveObjectsTests |
LiveObjects/Tests/AblyLiveObjectsTests |
LiveObjects native unit and integration tests |
AblySoakTests |
Test/AblySoakTests |
The soak test — see Soak test below. Skipped unless RUN_SOAK_TEST is set |
To run just one of them, filter by module name — for example swift test --filter 'AblyLiveObjectsTests\.'.
Every one of these targets selects its files by directory: SwiftPM globs the target's path, and the test plans name whole targets rather than individual tests. A new test file is therefore picked up automatically, with no change to Package.swift, to any test plan, or to any CI workflow. Note in particular that the ported LiveObjects objects UTS unit specs live inside the UTS target (under Test/UTS/unit/objects/), alongside the rest of the Universal Test Suite, so they run as part of that target rather than AblyLiveObjectsTests.
Both AblyLiveObjectsTests and the objects UTS suites also depend on a shared test-support target, AblyLiveObjectsTesting (Test/AblyLiveObjectsTesting), imported with @testable for internal-access test helpers and mocks. It is a regular (non-test) target, so it is compiled but never run on its own — which is why it is not listed above.
In CI:
-
integration-test.yamlruns the Fastlane lanes withsuite:sdk, which builds theably-pubsub-cocoascheme againstTest/Ably.xctestplanand passes-skip-testing:UTS, so it coversAblyTestsandAblyTestsObjCon all three platforms. -
uts.yamlruns the same lanes withsuite:uts(-only-testing:UTS), covering theUTStarget alone on all three platforms. It is the only place CI executes that target's tests, and therefore where the ported LiveObjectsobjectsunit specs run.Each platform runs twice, once per entry point. The
coreleg uses the defaultAblytest plan, and builds clients withPubSubClient(options:). Thedeviceleg usesTest/UTSDevice.xctestplan, whose configuration setsUTS_SIDE=device, and builds them withPubSubDevice.createClient(options:)instead.Test/UTS/README.mddocuments the seam.Test plans are declared in
.swiftpm/xcode/xcshareddata/xcschemes/ably-pubsub-cocoa.xcscheme. A plan is also how an environment variable reaches the test process underxcodebuild, where neither a plain export nor aTEST_RUNNER_-prefixed build setting does. Underswift testno plan is needed, because the test binary inherits the environment.The two are separate workflows because the UTS is primarily a unit suite, so grouping it under "Integration Test" misnamed it; splitting them also means a UTS failure is distinguishable from an
AblyTestsone without opening a log, and either can be dispatched or re-run without the other's sandbox time. Between them they cover every target in the test plan, withUTSrunning twice per platform, once perUTS_SIDEvalue. A lane invoked withoutsuite:still runs the whole plan, which is what a localbundle exec fastlane test_macOSdoes. -
liveobjects.yamlrunsAblyLiveObjectsTeststhree ways:swift test --filter 'AblyLiveObjectsTests\.', theAblyLiveObjectsscheme viaLiveObjects/BuildTool, and the code-coverage job. These are not equivalent —BuildTool test-libraryuses the scheme's defaultAllTestsplan, whereas the coverage job passes-testPlan UnitTests, which skips anything tagged.integration. It does not execute theUTStarget's tests (that'suts.yaml's job, above), though its SPM job still compiles the whole package —UTSincluded — under-warnings-as-errors. -
check-spm.yamlonly builds; it runs no tests.
No workflow runs the soak test.
AblySoakTests opens a hundred realtime connections and drives them for twenty minutes. There is no
server involved: the target supplies fake HTTP, WebSocket and reachability implementations that
answer with plausible protocol messages, close abruptly, fail and drop offline at random. The test
passes if nothing crashes, deadlocks or raises an exception along the way.
Because a run takes twenty minutes, it is skipped unless RUN_SOAK_TEST is set in the environment.
Run it by hand when you have changed connection, channel or presence state handling:
RUN_SOAK_TEST=1 swift test --filter 'AblySoakTests\.'The fakes reproduce the parts of the protocol the SDK reads, so a change to what the SDK expects
from the server can make them stop being realistic. Test/AblySoakTests/SoakTestWebSocket.swift
stamps each protocol message with a connection id and an id of the form <connectionId>:<serial>,
for instance, because presence members inherit both.
ably-cocoa allows users to pass in Ably-authored plugins via the ARTClientOptions.plugins property. These plugins extend the functionality of the SDK. For more information on the implementation of the plugins mechanism, see Docs/plugins.md.
The LiveObjects plugin lives in LiveObjects/ and is vended as this package's AblyLiveObjects product. It has its own CONTRIBUTING.md covering setup, tests, linting and coding guidelines; read that before working on plugin code.
Two things about the plugin affect the repository as a whole, and so are documented here rather than there.
Package.swift declares macOS 12, iOS 15, tvOS 15 for the whole package. SwiftPM platform requirements are package-wide, so one floor applies to every product.
Code that needs a newer OS than the package floor carries its own @available — for example Subscriber.swift, whose parameter packs require iOS/tvOS 17, along with every test that uses it. Note that swift-testing's @Suite macro rejects types marked @available, so a suite needing a newer OS has to annotate its test functions instead.
Swift Package Manager is the only distribution channel for 2.x. A release tag therefore delivers
both products — AblyPubSubDevice and AblyLiveObjects.
This was not always so: 1.x also shipped a CocoaPods pod and a Carthage Ably.xcframework, and
AblyLiveObjects was available through neither. Those channels stay on the 1.x line, which is
maintenance-only.
Per-declaration @available is what lets one package host components with different OS floors, which
is why the plugin no longer needs a repository of its own — see Docs/plugins.md.
- In Objective-C code, use
art_dispatch_syncandart_dispatch_asyncinstead ofdispatch_syncanddispatch_async, for more debuggable handling of the case in which we accidentally submit to anilqueue.
All time-dependent code in ably-cocoa goes through the injectable ARTTimeProvider abstraction (declared in Source/PrivateHeaders/Ably/ARTTimeProvider.h). This indirection allows the Universal Test Suite to install a single fake-time implementation that controls every clock-dependent code path across both ably-cocoa and any Ably-authored plugins.
New code MUST obtain time and scheduling primitives from an injected id<ARTTimeProvider> rather than calling system primitives directly. In particular:
- Don't call
[NSDate date](orDate()from Swift) directly. Use[timeProvider wallClockNow]. - Don't call
clock_gettime_nsec_np,mach_continuous_time, or similar continuous-clock primitives directly. Use[timeProvider continuousClockNow], which returns anid<ARTContinuousClockInstant>that supportsisAfter:andaddingDuration:. - Don't call
dispatch_after,NSTimer, ordispatch_source_set_timerdirectly to run something after a delay. Use[timeProvider scheduleAfter:queue:block:], which returns anid<ARTSchedulerHandle>that supportscancel.
Internal classes obtain their ARTTimeProvider by reading options.testOptions.timeProvider in their -init (the default value is an ARTSystemTimeProvider, backed by real system primitives) and stash it as an ivar, the same way the logger and the internal dispatch queue are passed in from the owning class. Downstream consumers (e.g. ARTEventEmitter) receive the provider as an init parameter from their owning class.
Source files must comply with the rules defined in .editorconfig (enforced by CI).
Many text editors — including Xcode, if the "Prefer settings from .editorconfig files" setting is switched on — can automatically follow these rules.
To check compliance locally, install editorconfig-checker (brew install editorconfig-checker) and run:
make lintThe repository has a single version number, applied to everything it publishes. Since the LiveObjects plugin moved into this repository it no longer has a version of its own: the standalone ably-liveobjects-swift-plugin package stopped at 0.4.1, and the first release of AblyLiveObjects from here carries this repository's next version number. There is no 0.x line to continue, and the plugin's historical changelog is kept only for reference.
For each release, the following needs to be done:
- Confirm that none of our
Package.swiftdependencies are specified using a fixed.revision. (The plugin-support library used to be the likeliest offender here; it is now the in-repo_AblyPluginSupportPrivatetarget rather than an external dependency, so it no longer needs its own release.) - Create a new branch
release/x.x.x(wherex.x.xis the new version number) from themainbranch - Run
make bump_[major|minor|patch]to bump the new version number. This will create a Git commit, push it to origin:git push -u origin release/x.x.x - Go to Github releases and press the
Draft a new releasebutton. Choose your new branch as a target - Press the
Choose a tagdropdown and start typing a new tag, Github will suggest theCreate new tag x.x.x on publishoption. After you select it Github will unveil theGenerate release notesbutton - From the newly generated changes remove everything that doesn't make much sense to the library user
- Copy the final list of changes to the top of the
CHANGELOG.mdfile. Modify as necessary to fit the existing format of this file - Commit these changes and push to the origin
git add CHANGELOG.md && git commit -m "Update change log." && git push -u origin release/x.x.x - Make a pull request against
mainand await approval of reviewer(s) - Once approved and/or any additional commits have been added, merge the PR (if you do this from Github's web interface then use the "Rebase and merge" option)
- After merging the PR, wait for all CI jobs for
mainto pass - Publish your drafted release:
- refer to previous releases for release notes format
- Checkout
mainlocally, pulling in changes usinggit checkout main && git pull. Make sure the new tag you need was created on publish - Test that Swift Package Manager resolves the new tag, selecting the
AblyPubSubDeviceandAblyLiveObjectsproducts