KZL 174 - Update README for SDK V6 #308

Aschen · 2018-09-10T12:45:27Z

What does this PR do?

This PR update the README to briefly explain how to use the SDK V6 until the documentation is available.

How should this be manually tested?

Step 1 : Read the readme, try the code example

Other changes

update deploy script (the one who build the dist/) to support the 6-beta branch

Boyscout

cosmetics on .travis.yml

codecov-io · 2018-09-10T12:49:14Z

Codecov Report

Merging #308 into 6-dev will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##            6-dev     #308   +/-   ##
=======================================
  Coverage   97.71%   97.71%           
=======================================
  Files          28       28           
  Lines        1401     1401           
=======================================
  Hits         1369     1369           
  Misses         32       32

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ba27a31...a240203. Read the comment docs.

ballinette

I would also add a notice within the About Kuzzle paragraph, saying that this is the documentation for the beta-6 SDK, which has been refactored in deep.

ballinette · 2018-09-11T08:14:21Z

README.md

+```
+
+## Protocols used
+Actuellement, le SDK supporte nativement 3 protocols: `http`, `websocket` et `socketio`.  


to be translated into English... ;)

ballinette · 2018-09-11T08:18:31Z

README.md

+## Protocols used
+Actuellement, le SDK supporte nativement 3 protocols: `http`, `websocket` et `socketio`.  
+
+The main reason behind this is that while Socket.IO offers better compatibility with older web browsers, our raw WebSocket implementation is about 20% faster


nitpicking: remove The main reasion behind this is that

just be decalarative, something like that:

Websocket and Socket.IO protocols implement the whole Kuzzle API, while HTTP protocol does not implement realtime features (rooms and subscriptions) While Socket.IO offers better compatibility with older web browsers, our raw WebSocket implementation is about 20% faster

ballinette · 2018-09-11T08:19:33Z

README.md

+
+#### NodeJS
+
+The protocol used is always raw WebSocket for `websocket`.


not true anymore. We can now choose btw http and websocket (and even socket.io if we want, whereas it is not a pertinent choice), or implement our custom protocol if needed.

ballinette · 2018-09-11T08:20:37Z

README.md

+
+#### Web Browsers
+
+If you choose `websocket`, the SDK will first try to use raw WebSocket to connect to Kuzzle. If the web browser does not support this protocol, then the SDK falls back to Socket.IO.


not true anymore: the application must now implement the fallback if we need it.
(maybe give a short example for that.)

ballinette · 2018-09-11T08:24:45Z

README.md

+}
+```
+
+### ISO with the Kuzzle API


open suggestion: we could also add an sample code with kuzzle.query method.

ballinette · 2018-09-11T08:25:24Z

README.md

+
+Any errors must be caught either at the end of the Promise chain, or by using `async/await` and a `try...catch`.
+
+Translated with www.DeepL.com/Translator


scottinet · 2018-09-11T08:54:58Z

README.md

+
+The main reason behind this is that while Socket.IO offers better compatibility with older web browsers, our raw WebSocket implementation is about 20% faster
+
+Which protocol is used when you connect to Kuzzle depends on multiple factors:


What protocol

I removed this sentence

scottinet · 2018-09-11T08:58:03Z

README.md

+}
+```
+
+### ISO with the Kuzzle API


Frenchism. Proposal: Close implementation of Kuzzle's API or Match Kuzzle's API

scottinet · 2018-09-11T08:59:29Z

README.md

+```
+
+The parameters of each method differ according to the parameters expected in the API.  
+To get the details of the parameters of each method, it is necessary for the moment to see the code of each controller on [Github](https://github.com/kuzzleio/sdk-javascript/tree/6-beta/src/controllers).


?

~~Should be removed. If you know API actions that aren't properly documented, write an issue instead so that we can fix these.~~

Ok I completely misunderstood what you wrote -_-

scottinet · 2018-09-11T09:02:14Z

README.md

+
+### Promise based
+
+Each SDK method returns a Promise resolving on the result of the API return (the `result` property described in the API documentation).  


All SDK methods return a promise resolving the result part of Kuzzle API responses. If an error occurs, the promise is rejected with an Error object embedding the error part of the API response.

scottinet · 2018-09-11T09:04:10Z

README.md

+
+For example, for the action `create` of the controller `collection` ([collection#create](https://docs.kuzzle.io/api-documentation/controller-collection/create)), the property `result` contains `{ "acknowledged": true} `. This is therefore what will be returned by the SDK method if successful.
+
+Any errors must be caught either at the end of the Promise chain, or by using `async/await` and a `try...catch`.


Any error

It doesn't seem useful to me to explain how a promise should be handled, I think that my proposal above is enough to document how errors are returned by SDK methods

I feel more confident when I see example along the documentation but if you think it's too much I can remove that part.

scottinet · 2018-09-11T09:05:13Z

README.md

+  .then(serverTime => console.log(serverTime))
+  .catch(error => console.error(error));
+
+// With async/await


What's the purpose of proving an async/await example?

Same reason as above

scottinet · 2018-09-11T09:05:43Z

README.md

+    hello: { type: 'text' }
+  }
+};
+// Without async/await


ditto: I don't think that this async/await example adds anything interesting to our documentation, we should stick to raw promises examples.

async/await feel more modern than then/catch. With the rise of async/await over raw promises, I think more and more people will be more comfortable with async/await syntax.

scottinet · 2018-09-11T09:06:59Z

README.md

+try {
+  const result = await kuzzle.collection.create('my-index', 'my-collection', mapping);
+  // result contain { "acknowledged": true }
+  console.log('Success');


console.log(result); seems more appropriate to me

ballinette · 2018-09-11T16:19:00Z

README.md


 You can access the Kuzzle repository on [Github](https://github.com/kuzzleio/kuzzle)

+This is the documentation for the beta-6 SDK. We are currently refactoring in deep our documentation to support many versions of each SDK. You can see it [here](https://docs-v2.kuzzle.io/sdk-reference/kuzzle/constructor/) but notice that this is an beta version of the documentation.  


s/this is an beta version/this is a beta version/

@ballinette

* KZL 174 - Update README for SDK V6 (#308) * Draft readme * Update README for sdk v6 * Update sdk deploy script to build * Use 6-beta links in github url * Apply change from @ballinette and @scottinet * typo * Release 6.0.0-beta-1 * dependencies update

Aschen added 3 commits September 10, 2018 12:02

Draft readme

cde36d7

Update README for sdk v6

6bda465

Update sdk deploy script to build

df693ad

Aschen added the changelog:enhancements label Sep 10, 2018

Aschen self-assigned this Sep 10, 2018

Use 6-beta links in github url

8530258

ballinette suggested changes Sep 11, 2018

View reviewed changes

scottinet changed the base branch from 6-beta to 6-dev September 11, 2018 08:46

scottinet suggested changes Sep 11, 2018

View reviewed changes

Apply change from @ballinette and @scottinet

78ba7d4

ballinette reviewed Sep 11, 2018

View reviewed changes

typo

a240203

ballinette approved these changes Sep 12, 2018

View reviewed changes

scottinet approved these changes Sep 12, 2018

View reviewed changes

scottinet merged commit f3a7a0e into 6-dev Sep 12, 2018

scottinet deleted the KZL-174/beta-version-sdk-6 branch September 12, 2018 15:36

scottinet mentioned this pull request Sep 13, 2018

Release 6.0.0-beta-1 #311

Merged

alexandrebouthinon mentioned this pull request Feb 21, 2019

6.0.0 proposal #377

Merged


		#### NodeJS

		The protocol used is always raw WebSocket for `websocket`.


		#### Web Browsers

		If you choose `websocket`, the SDK will first try to use raw WebSocket to connect to Kuzzle. If the web browser does not support this protocol, then the SDK falls back to Socket.IO.


		Any errors must be caught either at the end of the Promise chain, or by using `async/await` and a `try...catch`.

		Translated with www.DeepL.com/Translator


		The main reason behind this is that while Socket.IO offers better compatibility with older web browsers, our raw WebSocket implementation is about 20% faster

		Which protocol is used when you connect to Kuzzle depends on multiple factors:


		### Promise based

		Each SDK method returns a Promise resolving on the result of the API return (the `result` property described in the API documentation).


		For example, for the action `create` of the controller `collection` ([collection#create](https://docs.kuzzle.io/api-documentation/controller-collection/create)), the property `result` contains `{ "acknowledged": true} `. This is therefore what will be returned by the SDK method if successful.

		Any errors must be caught either at the end of the Promise chain, or by using `async/await` and a `try...catch`.


		You can access the Kuzzle repository on [Github](https://github.com/kuzzleio/kuzzle)

		This is the documentation for the beta-6 SDK. We are currently refactoring in deep our documentation to support many versions of each SDK. You can see it [here](https://docs-v2.kuzzle.io/sdk-reference/kuzzle/constructor/) but notice that this is an beta version of the documentation.

KZL 174 - Update README for SDK V6 #308

KZL 174 - Update README for SDK V6 #308

Uh oh!

Conversation

Aschen commented Sep 10, 2018

What does this PR do?

How should this be manually tested?

Other changes

Boyscout

Uh oh!

codecov-io commented Sep 10, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ballinette left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

scottinet Sep 11, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

codecov-io commented Sep 10, 2018 •

edited

Loading

scottinet Sep 11, 2018 •

edited

Loading