Status badges for GitHub workflows should appear here, under the initial H1.
- A manually maintained TOC (table of contents) should not be included. GitHub have been providing built-in, automatic support for the creation of README TOC since March 2021.
- Headings with the
[optional]suffix in this document are not required for all SDKs. - There will be some SDKs where additional headings may be required, where those headings need not necessarily be added to this template if they're clearly one-off requirements for the context of that particular SDK.
- The order of headings, from top to bottom, has been considered carefully so SDKs should not deviate from this without very strong reasons.
- Targeting developers using the SDK. Those who wish to contribute towards the SDK will want to refer to Contributing.
READMEs in any public repo should include the following "official" intro to Ably. It should be italicized as shown and appear before the Overview section. This helps visitors learn about who we are and what they can build with this SDK. This intro is not required in any sub-READMEs that are linked to from the main one.
Ably is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably’s platform to offload the growing complexity of business-critical realtime data synchronization at global scale. For more information, see the Ably documentation.
A one sentence summary of what this SDK does. Link to supported features and known limitations sections below.
Not all repositories will have this, but if there is an example app then this is often a good entry point for developers wishing to gain familiarity before attempting to integrate it into their own application codebase.
Example: ably-flutter
How to install this SDK into an application project (whether a new or existing codebase), covering all supported package management and distribution systems.
Provide a link to Requirements.
These are generally pretty basic but should show all code required to get something up and running with this SDK.
Links out to the core documentation relating to this SDK.
Example: ably-asset-tracking-android
Also, links out to other locations, typically hosted by Ably, where more useful detail can be found about this SDK and how it fits into the wider ecosystem. These links tend to fall outside the immediate linear reference provided by links provided under Documentation - e.g. tutorials, demo repositories, blog posts, etc..
Examples: ably-flutter, ably-asset-tracking-android
Demo repositories are mostly hosted in our ably-labs GitHub org. New demos should be indexed from the SDK repositories upon which they depend, under this heading.
What is required to build a project using this SDK. Typically a list of prerequisites.
Detail on what target runtimes are supported by this SDK. May also include detail around what platforms are tested on, though preference should be towards referring those who are interested in testing to consult workflow files directly (e.g. to inspect strategy matrix configuration for jobs).
Specify the version of the spec that this SDK targets and link to the feature support matrix.
A list of features that we do not currently support, but we do plan to add in the future.
This should be formatted as a bulleted list and each feature should link to an issue in this repository under which the work will be done when we come to implement it. This allows people to comment on or watch the issue if they are interested.
Example: ably-flutter
If there are no known limitations for this repository then this section, including heading, should be omitted. When removing this section from a readme then be careful to ensure that any links to it from that document, or other documents in the repository, are removed at the same time.
Example: ably-js
A sentence pointing potential contributors to another document (see sdk-contributing.md). This sentence should be in the form:
For guidance on how to contribute to this project, see [CONTRIBUTING.md](CONTRIBUTING.md).If applicable or otherwise courteous towards third parties who we've worked with or been supported by.
Example: ably-js