versioning docs

2022-04-28 11:15:38 +02:00
parent 0d770614cd
commit a3a23feb3e
86 changed files with 4503 additions and 0 deletions
@@ -0,0 +1,4 @@
+{
+  "label": "Introduction",
+  "position": 1
+}
@@ -0,0 +1,55 @@
+---
+id: choose_package
+sidebar_position: 2
+title: Choosing The Right Flutter Package
+---
+
+### Why the SDK is split into different packages
+
+Different applications need different levels of customization and integration with the Stream Chat SDK.
+To do this, the Flutter SDK is split into three different packages which build upon the last and give
+varying levels of control to the developer. The higher level packages offer better compatibility out of the
+box while the lower level SDKs offer fine grained control. There is also a separate package for persistence
+which allows you persist data locally which works with all packages.
+
+### How do I choose?
+
+#### The case for stream_chat_flutter
+
+For the quickest way to integrate Stream Chat with your app, the UI SDK (`stream_chat_flutter`) is the
+way to go. `stream_chat_flutter` contains prebuilt components that manage most operations like data
+fetching, pagination, sending a message, and more. This ensures you have a nearly out-of-the-box
+experience adding chat to your applications. It is also possible to use this in conjunction with
+lower level operations of the SDK to get the best of both worlds.
+
+:::note
+The package allows customization of components to a large extent making it easy to tweak the theme
+to match your app colors and such. If you require any additional feature or customization, feel free
+to request this through our support channels.
+:::
+
+<b>Summary:</b>
+
+For the quickest and easiest way to add Chat to your app with prebuilt UI components, use stream_chat_flutter
+
+
+#### The case for stream_chat_flutter_core
+
+If your application involves UI that does not fit in with the stream_chat_flutter components, stream_chat_flutter_core
+strips away the UI associated with the components and provides the data fetching and manipulation
+capabilities while supplying builders for UI. This allows you to implement your own UI and themes
+completely independently while not worrying about writing functions for data and pagination.
+
+<b>Summary:</b>
+
+For implementing your own custom UI while not having to worry about lower level API calls, use stream_chat_flutter_core.
+
+#### The case for stream_chat
+
+The stream_chat package is the Low-level Client (LLC) of Stream Chat in Flutter. This package wraps
+the underlying functionality of Stream Chat and allows the most customization in terms of UI, data,
+and architecture.
+
+<b>Summary:</b>
+
+For the most control over the SDK and dealing with low level calls to the API, use stream_chat.
@@ -0,0 +1,77 @@
+---
+slug: /
+id: introduction
+sidebar_position: 1
+title: About The Flutter SDK
+---
+Exploring The Basics Of Stream Chat
+
+![](../assets/sdk_title.png)
+
+Stream Chat is a service that helps you easily build a full chat experience in your Flutter apps.
+We also support a variety of other SDKs.
+
+This section of the documentation focuses on our Flutter SDK which helps you easily
+ship high quality messaging experiences in apps and programs built with the [Flutter toolkit
+made by Google](https://flutter.dev).
+
+The Stream Chat Flutter SDK comprises five different packages to choose from, ranging from ones
+giving you complete control to ones that give you a rich out-of-the-box chat experience.
+
+The packages that make up the Stream Chat SDK are:
+
+1. <b>Low Level Client (stream_chat)</b>: a pure Dart package that can be used on any Dart project.
+It provides a low-level client to access the Stream Chat service.
+2. <b>Core (stream_chat_flutter_core)</b>: provides business logic to fetch common things required
+for integrating Stream Chat into your application.
+The core package allows more customisation and hence provides business logic but no UI components.
+3. <b>UI (stream_chat_flutter)</b>: this library includes both a low-level chat SDK and a set of
+reusable and customisable UI components.
+4. <b>Persistence (stream_chat_persistence)</b>: provides a persistence client for fetching and
+saving chat data locally.
+5. <b>Localizations (stream_chat_localizations)</b>: provides a set of localizations for the SDK.
+
+We recommend building prototypes using the full UI package, [stream_chat_flutter](https://pub.dev/packages/stream_chat_flutter),
+since it contains UI widgets already integrated with Stream's API. It is the fastest way to get up
+and running using Stream chat in your app.
+
+The Flutter SDK enables you to build any type of chat or messaging experience for Android, iOS, Web
+and Desktop.
+
+If you're building a very custom UI and would prefer a more lean package,
+[stream_chat_flutter_core](https://pub.dev/packages/stream_chat_flutter_core) will be suited to this
+use case. Core allows you to build custom, expressive UIs while retaining the benefits of our full
+Flutter SDK. APIs for accessing and controlling users, sending messages, and so forth are seamlessly integrated
+into this package and accessible via providers and builders.
+
+Before going into the docs, let's take a small detour to look at how the elements of Stream Chat are structured.
+
+### Basic Structure
+
+There are two core elements in chat, <b>Users</b> and <b>Channels</b>.
+Channels are groups of one or more users that can message each other.
+In an app, you need to have a user connected to query channels.
+
+There is no specific distinction between a chat with only two people and a group chat,
+but there is a way to create a unique chat between a certain number of people by creating a <b>distinct</b> channel.
+
+![](../assets/chat_basics.png)
+
+In essence, a normal two-person chat would be a <b>distinct channel</b> created with two members (you cannot add or delete members in this channel), whereas a group created with two people would simply be a <b>non distinct channel</b> (possible to add or remove members).
+
+:::note
+It is also possible to add more than two people in a distinct channel which retains the same add/removal properties and resembles the Slack DMs where you can DM one or more people as well.
+:::
+
+In summary, if you were creating a Whatsapp-like app, the first screen would be a <b>list of channels</b> - which on opening would show a <b>list of messages</b> that were sent by the users in the Channel.
+
+While this is a simplistic overview of the service, the Flutter SDK handles the UI and more time consuming things (media upload, offline storage, theming, etc.) for you.
+
+Before reading the docs, consider trying our [online API tour](https://getstream.io/chat/get_started/),
+it is a nice way to learn how the API works.
+It's in-browser so you'll need to use Javascript but the core conceps are pretty much the same as Dart.
+
+You may also like to look at the [Flutter tutorial](https://getstream.io/chat/flutter/tutorial/)
+which focuses on using the UI package to get Stream Chat integrated into a Flutter app.
+
+Further sections break down each individual packages and explain several common operations.
@@ -0,0 +1,20 @@
+---
+id: versioning_policy
+sidebar_position: 3
+title: Versioning Policy
+---
+
+All of the Stream Chat packages follow [semantic versioning (semver)](https://semver.org/).
+
+That means that with a version number x.y.z (major.minor.patch):
+- When releasing bug fixes (backwards compatible), we make a patch release by changing the z number (ex: 3.6.2 to 3.6.3). A bug fix is defined as an internal change that fixes incorrect behavior.
+- When releasing new features or non-critical fixes, we make a minor release by changing the y number (ex: 3.6.2 to 3.7.0).
+- When releasing breaking changes (backward incompatible), we make a major release by changing the x number (ex: 3.6.2 to 4.0.0).
+
+See the [semantic versioning](https://dart.dev/tools/pub/versioning#semantic-versions) section from the Dart docs for more information.
+
+This versioning policy does not apply to prerelease packages (below major version of 1). See this
+[StackOverflow thread](https://stackoverflow.com/questions/66201337/how-do-dart-package-versions-work-how-should-i-version-my-flutter-plugins)
+for more information on Dart package versioning.
+
+Whenever possible, we will add deprecation warnings in preparation for future breaking changes.