From aa5bd29218ddec361895727137d4f3dc32823db2 Mon Sep 17 00:00:00 2001 From: Zita Szupera Date: Wed, 26 Jul 2023 16:25:38 +0200 Subject: [PATCH] docs: Readme for js client, contributing guide --- CONTRIBUTING.md | 98 +++++++++++++++++++++++++ README.md | 150 +++++++++++++++++++------------------- README.txt | 41 ----------- packages/client/README.md | 62 ++++++++++++++-- 4 files changed, 226 insertions(+), 125 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 README.txt diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..158ec97069 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,98 @@ +Hi 👋 + +We're happy that you'd like to contribute to this project. The following guide will help you get started. + +## Setting up your local environment + +### Install dependencies + +Run the following command in the repository root + +``` +yarn install +``` + +### Build packages + +``` +yarn build:all +``` + +There are also build scripts for individual packages in case you don't need to build everything. + +### Running packages + +This repository contains multiple packages. Depending on your contribution you'll need to run some of these. Please refer to the [package overview](./README.md#projectspackages-) to understand which are the relevant packages for you. + +Each package has the necessary scripts inside the root [`package.json`](./package.json) file. + +Please note that some packages could require extra setup steps: + +- please check the README of each package as well +- please check for `.env-example` files that show you how to create a local `.env` file for the given package to hold credentials + +### Running docs + +Some packages contain documentation pages, these are located in the `docusaurus` folder of the given package's root directory (for example: `packages/react-sdk/docusaurus`). + +To run them: + +```bach +# navigate to the given package +cd packages/react-sdk +# start docs +stream-chat-docusaurus -s +``` + +Follow this guide to set up [stream-chat-docusaurus](https://github.com/GetStream/stream-chat-docusaurus-cli) + +## Guidelines + +### React SDK + +- Don't forget to update the documentation located in `packages/react-sdk/docusaurus` +- If you need to update tutorials, don't forget to also update the [relevant codesandboxes](https://codesandbox.io/dashboard/recent?workspace=cc639528-2089-4e83-ad4c-d161569e2f37) as well (in case we have one) +- Don't forget to update relevant sample apps located in `sample-apps/react` + +### React Native SDK + +- Don't forget to update the documentation located in `packages/react-native-sdk/docusaurus` + // TODO + +### Client + +- Don't forget to add/update unit and/or integration tests +- Documentation for the Node.js client lives in the [protocol repository](https://github.com/GetStream/protocol), don't forget to update that + +#### SFU API changes (internal) + +To update SFU models and API endpoints [generate ts client](https://github.com/GetStream/protocol#generate-sdk-with-docker) and copy the files to the `packages/client/src/gen` folder. + +#### Coordinator API changes (internal) + +We have a shell script which will generate the Coordinator models from the OpenAPI spec. +This script expects the following directory structure to be set up: + +- `chat` - the `chat` repository +- `stream-video-js` - current repository +- `cd stream-video-js/packages/client && yarn generate:open-api:dev` + +Alternatively you can use the following script `cd stream-video-js/packages/client && yarn generate:open-api` to generate the models from the [protocol repository](https://github.com/GetStream/protocol). + +## PRs + +- CI checks are running on PRs, please pay attention to them, and fix issues in case an action fails +- Many sample applications are deployed to a preview environment, you can check your changes there as well, check the relevant action's output for links (some application are internal, and only available to Stream developers) +- (internal) documentation is deployed to the [staging docs site](https://staging.getstream.io/video/docs/), you can check your changes there as well + +## Release flow (internal) + +Commits to `main` will trigger the following CI steps: + +- Version and release all changed packages + - The new version is calculated automatically based on [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) + - The release configuration for each public package can be found in the `packages//project.json` file + - For more information checkout the documentation of the [release tool](https://github.com/jscutlery/semver) we are using + - [Known issue about the release process](https://getstream.slack.com/archives/C04ATV49DU3/p1687161389232829) +- Documentation is deployed to the [production site](https://getstream.io/video/docs/). An exception is the Node.js documentation, which needs to be deployed separately (see above for more details). +- All relevant sample apps will be deployed diff --git a/README.md b/README.md index d6d2de4105..92caeacb49 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,77 @@ - -# Stream Video for JavaScript - -[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=GetStream_stream-video-js&metric=alert_status&token=fdc1439303911957da9c7ff2ce505f94c3c14d36)](https://sonarcloud.io/summary/new_code?id=GetStream_stream-video-js) +# Stream Video for JavaScript + +[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=GetStream_stream-video-js&metric=alert_status&token=fdc1439303911957da9c7ff2ce505f94c3c14d36)](https://sonarcloud.io/summary/new_code?id=GetStream_stream-video-js) Stream Video for Javascript Header image - -## **Quick Links** - -- [Register](https://getstream.io/chat/trial/) to get an API key for Stream Video -- [React SDK](./packages/react-sdk#official-react-sdk-for-stream-video) -- [React Native SDK](./packages/react-native-sdk#official-react-native-sdk-for-stream-video) - -## What is Stream? - -Stream allows developers to rapidly deploy scalable feeds, chat messaging and video with an industry leading 99.999% uptime SLA guarantee. - -With Stream's video components, you can use their SDK to build in-app video calling, audio rooms, audio calls, or live streaming. The best place to get started is with their tutorials: - -- Video & Audio Calling Tutorial -- Audio Rooms Tutorial -- Livestreaming Tutorial - -Stream provides UI components and state handling that make it easy to build video calling for your app. All calls run on Stream's network of edge servers around the world, ensuring optimal latency and reliability. - -## 👩‍💻 Free for Makers 👨‍💻 - -Stream is free for most side and hobby projects. To qualify, your project/company needs to have < 5 team members and < $10k in monthly revenue. Makers get $100 in monthly credit for video for free. - -## 💡Supported Features💡 - -Here are some of the features we support: - -- Developer experience: Great SDKs, docs, tutorials and support so you can build quickly -- Edge network: Servers around the world ensure optimal latency and reliability -- Chat: Stored chat, reactions, threads, typing indicators, URL previews etc -- Security & Privacy: Based in USA and EU, Soc2 certified, GDPR compliant -- Dynascale: Automatically switch resolutions, fps, bitrate, codecs and paginate video on large calls -- Screen sharing -- Picture in picture support -- Active speaker -- Custom events -- Geofencing -- Notifications and ringing calls -- Opus DTX & Red for reliable audio -- Webhooks & SQS -- Backstage mode -- Flexible permissions system -- Joining calls by ID, link or invite -- Enabling and disabling audio and video when in calls -- Flipping, Enabling and disabling camera in calls -- Enabling and disabling speakerphone in calls -- Push notification providers support -- Call recording -- Broadcasting to HLS - -## Repo Overview 😎 - -This repo contains projects and samples developed by the team and Stream community. Projects are broken up into directories containing the source code for each project. - -## **Projects/Packages 🚀** - -- `packages`: contains all packages our customers can install and use in their apps. -- `packages/client`: our low-level client. It manages the lifecycle of a call, connects to our platform, and maintains the call state. The core part of our SDKs. -- `packages/react-bindings`: a set of React utilities and hooks that make it easy to work with the call state exposed by the `client` in React and React Native Apps. -- `packages/react-sdk`: the place where our React SDK lives. -- `packages/react-native-sdk`: the place where our React Native SDK lives. -- `packages/styling`: our theme stylesheets live here. -- `packages/i18n`: a utility package that takes care of internationalization support for our SDKs. -- `sample-apps/react/*`: contains a few sample apps that we have built to showcase our SDK and platform capabilities -- `sample-apps/react-native/*`: a collection of React Native sample apps for showcasing our SDK and platform - -## Contributing - -- How can I submit a sample app? - - Apps submissions are always welcomed! 🥳 Open a pr with a proper description and we'll review it as soon as possible -- Spot a bug 🕷 ? - - We welcome code changes that improve the apps or fix a problem. Please make sure to follow all best practices and add tests if applicable before submitting a Pull Request on Github. +## **Quick Links** + +- [Register](https://getstream.io/chat/trial/) to get an API key for Stream Video +- [React SDK](./packages/react-sdk#official-react-sdk-for-stream-video) +- [React Native SDK](./packages/react-native-sdk#official-react-native-sdk-for-stream-video) + +## What is Stream? + +Stream allows developers to rapidly deploy scalable feeds, chat messaging and video with an industry leading 99.999% uptime SLA guarantee. + +With Stream's video components, you can use their SDK to build in-app video calling, audio rooms, audio calls, or live streaming. The best place to get started is with their tutorials: + +- Video & Audio Calling Tutorial +- Audio Rooms Tutorial +- Livestreaming Tutorial + +Stream provides UI components and state handling that make it easy to build video calling for your app. All calls run on Stream's network of edge servers around the world, ensuring optimal latency and reliability. + +## 👩‍💻 Free for Makers 👨‍💻 + +Stream is free for most side and hobby projects. To qualify, your project/company needs to have < 5 team members and < $10k in monthly revenue. Makers get $100 in monthly credit for video for free. + +## 💡Supported Features💡 + +Here are some of the features we support: + +- Developer experience: Great SDKs, docs, tutorials and support so you can build quickly +- Edge network: Servers around the world ensure optimal latency and reliability +- Chat: Stored chat, reactions, threads, typing indicators, URL previews etc +- Security & Privacy: Based in USA and EU, Soc2 certified, GDPR compliant +- Dynascale: Automatically switch resolutions, fps, bitrate, codecs and paginate video on large calls +- Screen sharing +- Picture in picture support +- Active speaker +- Custom events +- Geofencing +- Notifications and ringing calls +- Opus DTX & Red for reliable audio +- Webhooks & SQS +- Backstage mode +- Flexible permissions system +- Joining calls by ID, link or invite +- Enabling and disabling audio and video when in calls +- Flipping, Enabling and disabling camera in calls +- Enabling and disabling speakerphone in calls +- Push notification providers support +- Call recording +- Broadcasting to HLS + +## Repo Overview 😎 + +This repo contains projects and samples developed by the team and Stream community. Projects are broken up into directories containing the source code for each project. + +## **Projects/Packages 🚀** + +- `packages`: contains all packages our customers can install and use in their apps. +- `packages/client`: our low-level client. It manages the lifecycle of a call, connects to our platform, and maintains the call state. The core part of our SDKs. Runs in browser and Node.js environments. +- `packages/react-bindings`: a set of React utilities and hooks that make it easy to work with the call state exposed by the `client` in React and React Native Apps. +- `packages/react-sdk`: the place where our React SDK lives. +- `packages/react-native-sdk`: the place where our React Native SDK lives. +- `packages/styling`: our theme stylesheets live here for web SDKs. +- `packages/i18n`: a utility package that takes care of internationalization support for our SDKs. +- `sample-apps/react/*`: contains a few sample apps that we have built to showcase our SDK and platform capabilities +- `sample-apps/react-native/*`: a collection of React Native sample apps for showcasing our SDK and platform + +## Contributing + +- How can I submit a sample app? + - Apps submissions are always welcomed! 🥳 Open a pr with a proper description and we'll review it as soon as possible +- Spot a bug 🕷 ? + - We welcome code changes that improve the apps or fix a problem. Please make sure to follow all best practices and add tests if applicable before submitting a Pull Request on Github. diff --git a/README.txt b/README.txt deleted file mode 100644 index 738a9ae9f0..0000000000 --- a/README.txt +++ /dev/null @@ -1,41 +0,0 @@ -# Stream Video JS SDK - -[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=GetStream_stream-video-js&metric=alert_status&token=fdc1439303911957da9c7ff2ce505f94c3c14d36)](https://sonarcloud.io/summary/new_code?id=GetStream_stream-video-js) - -## Dependencies - -Before you can run this project locally, the backend services has to be set up. In order to do so, -clone them and follow their appropriate READMEs found in their root. - -- [GetStream/video](https://github.com/GetStream/video) - Coordinator API -- [GetStream/video-sfu](https://github.com/GetStream/video-sfu) - SFU API -- [GetStream/video-proto](https://github.com/GetStream/video) - Proto files and client generation scripts - -## Setup - -1. Clone this repository `git clone https://github.com/GetStream/stream-video-js.git` -2. Install dependencies by running `yarn install` in the root of this repo -3. Build all packages `yarn clean:all && yarn build:all` - -## Running the apps - -### React Dogfood app (aka: Stream Calls) - -1. Follow the setup procedure in [packages/react-dogfood](packages/react-dogfood/README.md) - -### React Sample app - -Run the application `yarn start:react:app` (make sure the server is already running) - -1. It could happen that the compiler emits compile error due to corrupted babel cache -2. Run: `rm -rf packages/react-sample-app/node_modules/.cache` -3. Re-run the app `yarn start:react:app` - -If you want to connect to the SFU and the coordinator running locally, you have to change the URL in -[App.tsx](packages/react-sample-app/src/App.tsx). It should look something like this - -Then recompile the app - step (3) in [Setup](#setup) section here and then `yarn start:react:app`. - -### React Native - -Run the application by following these [steps](https://github.com/GetStream/stream-video-js/blob/main/packages/react-native-dogfood/README.md) diff --git a/packages/client/README.md b/packages/client/README.md index 7842746254..7d1de14c87 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -1,14 +1,60 @@ # @stream-io/video-client -🚧 **WARNING** This package is not yet stable, it is for internal use only. For more information check out our [video product page](https://getstream.io/video/). +🚧 **WARNING** This package is not yet stable, it is for internal use only. For more information check out our [video product page](https://getstream.io/video/). 🚧 -This package holds the autogenerated Protobuf code and clients. +Low-level video client for browser and Node.js integrations. -## Generate Coordinator Models from OpenAPI spec (Dev Mode): +## **Quick Links** -We have a shell script which will generate the Coordinator models from the OpenAPI spec. -This script expects the following directory structure to be set up: +- [Register](https://getstream.io/chat/trial/) to get an API key for Stream Video + TODO: add links to docs and tutorials -- `chat` - the `chat` repository -- `stream-video-js` - current repository -- `cd stream-video-js/packages/client && yarn generate:open-api` +## What is Stream? + +Stream allows developers to rapidly deploy scalable feeds, chat messaging and video with an industry leading 99.999% uptime SLA guarantee. + +With Stream's video components, you can use their SDK to build in-app video calling, audio rooms, audio calls, or live streaming. The best place to get started is with their tutorials: + +- Video & Audio Calling Tutorial +- Audio Rooms Tutorial +- Livestreaming Tutorial + +Stream provides UI components and state handling that make it easy to build video calling for your app. All calls run on Stream's network of edge servers around the world, ensuring optimal latency and reliability. + +## 👩‍💻 Free for Makers 👨‍💻 + +Stream is free for most side and hobby projects. To qualify, your project/company needs to have < 5 team members and < $10k in monthly revenue. Makers get $100 in monthly credit for video for free. + +## 💡Supported Features💡 + +Here are some of the features we support: + +- Developer experience: Great SDKs, docs, tutorials and support so you can build quickly +- Edge network: Servers around the world ensure optimal latency and reliability +- Chat: Stored chat, reactions, threads, typing indicators, URL previews etc +- Security & Privacy: Based in USA and EU, Soc2 certified, GDPR compliant +- Dynascale: Automatically switch resolutions, fps, bitrate, codecs and paginate video on large calls +- Screen sharing +- Picture in picture support +- Active speaker +- Custom events +- Geofencing +- Notifications and ringing calls +- Opus DTX & Red for reliable audio +- Webhooks & SQS +- Backstage mode +- Flexible permissions system +- Joining calls by ID, link or invite +- Enabling and disabling audio and video when in calls +- Flipping, Enabling and disabling camera in calls +- Enabling and disabling speakerphone in calls +- Push notification providers support +- Call recording +- Broadcasting to HLS + +## Contributing + +- How can I submit a sample app? + - Apps submissions are always welcome. 🥳 Open a PR with a proper description and we'll review it as soon as possible. +- Spot a bug 🕷 ? + - We welcome code changes that improve the apps or fix a problem. Please make sure to follow all best practices and add tests if applicable before submitting a Pull Request on Github.