Platform support documentation

[mattheworiordan]

@withakay a customer asked us today if PCL is supported (support ticket 2741). I noticed in the README it says "Currently a portable (PCL) version is not available.", however that's pretty well hidden.

Given we have questions about whether the library supports X platform, or works with Unity for example, or particular versions of Xamarin / Mono etc. I think it's time we added a section in the README perhaps called "Supported platforms" with details on which platforms we support 100%, which ones we do support somewhat with caveats and which are not support.

@funkyboy I know you recently addressed this in iOS as well. I think we could afford to have a section in the README specifically on this, perhaps linked from the top of the README under installation such as You can install Ably via [X] or manually on [supported platforms](linked)."

@funkyboy could you perhaps propose a generic solution for this across all our SDKs so that we have a standard. Could you also review our docs to see if anything needs to be done there too?

@withakay once @funkyboy has confirmed our approach, can you update this repo?

Also, should I tell the customer PCL is not supported? If so, may I ask why?

cc @paddybyers

[funkyboy]

@mattheworiordan @withakay Yup, we started yesterday with iOS. And at the beginning of the README. We might even make it more explicit and create a section for that so there's also a title.

I propose to state it positively: "This SDK supports x, y and z".

Note: Maybe we didn't state it clearly yet in the guidelines, but "supports platform x" means that we are running tests on that platform before releasing.

[withakay]

@mattheworiordan

should I tell the customer PCL is not supported? If so, may I ask why?

PCL is not supported, or perhaps better stated we do not offer a PCL compatible version. This was not a decision I was involved with (before my time) but I think the decision was probably valid, below are some of the reasons I think this.

tl;dr: It is hard to back port to PCL, PCLs have been replaced by .Net Standard, we have an alternative for the primary use case (Xamarin).

PCLs offer a subset of the APIs available in the full dotnet framework, there are various platforms and profiles that can be targeted (many of which are subsets of each other) the more platforms one wants to target the smaller API surface area gets. This is complicated further when one considers dependencies, which must also be PCLs and fit into the Platform and Profile target it becomes a bit of a rabbit hole. This was recognised by the .Net team and PCLs are now deprecated in favour of the .Net Standard 2.0 (which we do support)

The primary use case for PCLs is with Xamarin, unfortunately the tooling (i.e. Visual Studio) has not quite caught up so making .Net Standard Xamarin Apps requires manually editing project files and that, combined with technical debt from existing projects (I assume) means PCLs will probably not die in a hurry.

But the good news is we have iOS and Android compatible libraries that can be used with Xamarin, there is a little more setup that can feel a bit clunky, but it is not difficult to do.

[withakay]

@mattheworiordan @funkyboy Perhaps you could fork this repo to GitHub.com/ably-forks ? https://github.com/withakay/app-monkeychat

I can then update the README with a note about PCLs and Xamarin support and link to the repo as an example of how to setup a Xamarin app?

[funkyboy]

@withakay that's already a fork of a fork. I'd definitely keep an official repo under the Ably org as an example to showcase how to set up a project with our SDKs. Agree @mattheworiordan?

[withakay]

@funkyboy Yes, the source is originally from James Montemagno who is the PM of Mobile Developer Tools at Microsoft, the app originally used Twillio as the message bus, I ported it to use ably.

[funkyboy]

@withakay If there's any issue with credits we can add them to the README.

[mattheworiordan]

'd definitely keep an official repo under the Ably org as an example to showcase how to set up a project with our SDKs. Agree @mattheworiordan?

Sure. We have plenty of repos prefixed with demo-

[mattheworiordan]

I propose to state it positively: "This SDK supports x, y and z".

I think we need to be far more explicit than just having a line of text in a README with thousands of lines. We should standardise how we describe platform support for all libraries, and can be explicit then about older platforms perhaps working, but not being officially supported, with appropriate links to old versions. We should also then explicitly link from our primary ably documentation perhaps to this from the install / usage instructions pages.

@paddybyers @Srushtika please add your thoughts;.

[mattheworiordan]

P.S. We can move that to a separate issue in docs if you wish, please @funkyboy @Srushtika do that if you feel appropriate.

[funkyboy]

I don't understand if this issue is related to supported platform in the readme or in the documentation. Clearly we need to declare supported platforms in both places, but I'd keep it short (when possible) in the readme.

[mattheworiordan]

don't understand if this issue is related to supported platform in the readme or in the documentation.

Both, developers use both whether we like it or not.

I'd keep it short (when possible) in the readme.

Why? Why not be verbose about what we know we support in full, what we think we may support but perhaps don't test, which old platforms we support with unsupported older versions of the lib, and which we know we don't support. Of course in some cases this will be short, but in others where there are lots of platform incompatibilities / issues it won't.

[funkyboy]

Isn't showing that "it might work with older versions" conflicting a bit with our aim to push towards the adoption of last official release?

[funkyboy]

@withakay FYI, there's a new version of the "Supported Platforms" section in iOS and we are working on the one for JS now.

[mattheworiordan]

@withakay I assume we can close this issue now? If you agree, then could we add a comment to the PCL statement on our supported platforms section and link to https://github.com/ably/ably-dotnet/issues/182#issuecomment-366939087 explaining why?

[withakay]

@mattheworiordan I think so. It is worth mentioning that the tooling has now caught up and all versions Visual Studio can create Xamarin Form projects that target .Net Standard 2.0

[mattheworiordan]

Ah, that's great

[marto83]

@mattheworiordan and @withakay. I had a look at the Readme and it's been updated with supporting platforms.