onflow / flow

Flow is a fast, secure, and developer-friendly blockchain built to support the next generation of games, apps, and the digital assets that power them 🌊
https://onflow.org
Apache License 2.0
360 stars 164 forks source link

Flow SDK Guidelines #497

Open JeffreyDoyle opened 3 years ago

JeffreyDoyle commented 3 years ago

In order to provide SDK developers with expectations for what functionality a Flow SDKs should provide, we must create a language agnostic SDK spec. This specification should outline what functionality a Flow SDK should provide. The specification should not specify how such functionality must be achieved.

The outcome should be a specification for what functionality a Flow SDK must provide. Depending on which language implements the SDK spec, it should be flexible enough such that the varying features of such language can be utilized. The aim being that each Flow SDK can feel friendly and intuitive to users of the SDK's language, yet function with feature parity to Flow SDKs of other languages.

The Flow SDK spec will standardize a new "layer" of abstraction between the Flow protocol, Access API, Flow SDK and a developers application.

Layer 0: Flow Protocol Layer 1: Access API Layer 2: Flow SDK Spec <- New! Introduced by this issue. Layer 3: A Flow SDK implementation. Layer 4: A developers application.

Further Questions

Expected Outcomes

10thfloor commented 3 years ago

@JeffreyDoyle Could you point to any well-implemented specs as prior art? This could help with requirements here.

sideninja commented 3 years ago

Context & Purpose

The SDK Guidelines will provide us with a framework to build SDKs that will be:

Language agnostic rules that will allow developers to build a library that will comply with a "standard".

Process:

Building

Documentation

Testing

Maintaining

The next steps in the proposed process would be to move this to a repository centered around (SDK) guidelines. That would become a home and source of truth for providing guidelines, test data, documentation structures, ubiquitous language, track feature requests. This issue is a pre-draft, a source of information to include in the draft published in the repo after. We should make sure that we cover all important topics we want to define in this pre-draft version.

bluesign commented 3 years ago

First of all, it is a great write-up @sideninja, covers almost all points pretty well.

I have only one question and comment about testing.

The first critical question is I read before "Access Node REST API in development" in a GitHub issue (https://github.com/onflow/flow/issues/535)

Testing

Now all is good and solid, but we have a problem in general about SDK development, which this guideline not covers.

As far as I know current status:

But rest is very problematic. The main attitude on SDK development is currently people sharing what they have done for their own use and covers their cases. Either they don't have time, or they have moved on to something else.

This guideline requires serious maintainer(s), I think this should be organized somehow by you without leaving to the community. I think maybe you can kickstart SDKs, then give them to some community maintainer to maintain (for future improvements, handling breaking changes, etc). If he/she is not keeping up find a new maintainer.

I don't know how much time you spent for Go or js SDK, but developing an SDK with these specs is not an easy task, and to be honest, I don't think it will succeed. I don't know the exact ratio, but I think there is a big N for: (number of SDK users in Language X) / (for number of volunteer SDK developers in Language X)

sideninja commented 3 years ago

Thank you for providing feedback on this.

The first critical question is I read before "Access Node REST API in development" in a GitHub issue (#535)

We are currently developing a REST API that will become the preferred way to communicate with access nodes. I understand we have communication problems about changes like that, and the guidelines repo will help with part of that by becoming one place to communicate things around the SDK changes which would flag similar issues or upcoming changes. Developer communications are constantly improving and although we are aware of issues it will take us some time to improve, but I understand the concerns.

Testing

  • I think here is better to provide some mocking endpoint and specs of tests. So keeping eye on what SDKs are implemented, what is missing with CI, or any breaking changes implemented, etc can be good.

I was thinking of providing some specs but also support with mock data, can you elaborate more on your idea of providing mocking endpoints? I'm not quite sure I understand.

  • Most problems here are about making wrong requests, or missing requests (not implemented)

Now all is good and solid, but we have a problem in general about SDK development, which this guideline not covers.

As far as I know current status:

  • js and go sdk's are official and not much problem there.
  • python and dart seem like managed by flow employees. (I am not sure if they are committed to go with this spec or somehow flow will somehow make them official)

But rest is very problematic. The main attitude on SDK development is currently people sharing what they have done for their own use and covers their cases. Either they don't have time, or they have moved on to something else.

This guideline requires serious maintainer(s), I think this should be organized somehow by you without leaving to the community. I think maybe you can kickstart SDKs, then give them to some community maintainer to maintain (for future improvements, handling breaking changes, etc). If he/she is not keeping up find a new maintainer.

I don't know how much time you spent for Go or js SDK, but developing an SDK with these specs is not an easy task, and to be honest, I don't think it will succeed. I don't know the exact ratio, but I think there is a big N for: (number of SDK users in Language X) / (for number of volunteer SDK developers in Language X)

I agree and this is the biggest problem we need to solve. We prefer community first development when it comes to SDKs. We are aware this will be a huge challenge but you can only solve one problem at a time and the first problem to get there is to write guidelines. We will also try to establish an internal SDK advocate who will help and keep in touch with the SDKs maintainers. Do you have any ideas on how we could better incentivize the community to develop the SDKs? We actually discussed idea of bootstrapping but we are on the fence if it is good or not, since it might feel like it is not a community effort but our command and rules how to do things which we don't like.

bluesign commented 3 years ago

REST API will be very good solution, and speed up development of SDKs I believe.

For testing part: I was thinking like let's say I am developing a python SDK, instead of mocking everything myself. In guidelines there will be some spec (I think it is what you called user stories)

I will have a test.py ( which I will define in a spec file in repo)

Also this service can have some test utility functions

As this service will have always up to date spec, it is better to do testing over spec on your side.

So this tests will be step by step development guide. ( even can be some multiple step ones, sendTransaction, getResult, sendResult to verify etc)

SDK advocate is a very good idea, but incentivize part is very hard for me to tell, I am incentivized only by the good feeling I am getting back, but some SDK developers can be incentivized by some kind of résumé building, it is hard to predict. But the main problem is number of developers are very low :(

Main problem with maintainers are use-as-is mentality, I tried to contribute to 3 SDKs so far, only Dart implemented by bug report or pull request :)

Anyway I will try to bootstrap some for sure, fingers crossed for REST endpoint :)

sideninja commented 3 years ago

For testing part: I was thinking like let's say I am developing a python SDK, instead of mocking everything myself. In guidelines there will be some spec (I think it is what you called user stories)

Exactly, the user stories will guide you through development and give you an easy way to test.

then I will point my endpoint to https://sdk-test.onflow.org. (I can add some HTTP-HEADER like Test-Id: SINGLE_SIGNER)

Ohh, ok I see. We were thinking of having tests sets you would use to mock the response. Having a good architecture of the SDK it would allow you to isolate network responses and be possible to swap between mock and network implementation easily, but then again I really like this idea of not actually having test data but test API. It will ease the development, it would provide us insight into SDKs that are passing the tests. Thank you so much for this idea, I think this will be the way to go.

SDK advocate is a very good idea, but incentivize part is very hard for me to tell, I am incentivized only by the good feeling I am getting back, but some SDK developers can be incentivized by some kind of résumé building, it is hard to predict. But the main problem is number of developers are very low :(

If only the world would be full of people like you :) but yes the challenge is real.

REST endpoints are coming :)

bjartek commented 3 years ago

This is a good example of a well written spec and tck i think https://github.com/reactive-streams/reactive-streams-jvm/blob/v1.0.3/README.md#specification

sideninja commented 3 years ago

NEW: Feature Domains

SDK guidelines could define feature domains. Feature domain would be a group of actions that are related and their definition would live in the SDK guidelines repo. Each language-specific implementation of the SDK could then implement an arbitrary set of feature domains and be advertised as such thus removing the idea of one SDK per language to rule them all. For example, some feature sets would make more sense to be reused alongside backend services while others could be reused more on the frontend.

The feature set we would initially define would cover the current SDK functionality but this concept could be more scalable going forward as more feature sets occur (things like wallet discovery,...). The benefit of having more smaller defined feature sets could also be beneficial for making SDKs as small as possible which means easier to maintain and easier to create. Let's repeat an old mantra: Do one thing and do it well.

bluesign commented 3 years ago

@sideninja that's nice, composability for SDKs :)