docs: unify READMEs across backend repos (#84)

Author: peterdeme

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+
+# :recycle: Contributing
+
+We welcome code changes that improve this library or fix a problem, please make sure to follow all best practices and add tests if applicable before submitting a Pull Request on Github. We are very happy to merge your code in the official repository. Make sure to sign our [Contributor License Agreement (CLA)](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform) first. See our license file for more details.
+
+## Getting started
+
+### Install dependencies
+
+```shell
+$ bundle install --path vendor/bundle
+```
+
+### Run tests
+
+```shell
+$ STREAM_KEY=my_api_key STREAM_SECRET=my_api_secret bundle exec rake spec
+```
+
+### Linters and type check
+
+We use [Rubocop](https://github.com/rubocop/rubocop) for linting and [Sorbet](https://sorbet.org/) for type checking.
+
+To run them:
+```shell
+$ bundle exec rake rubocop
+$ bundle exec srb tc
+```
+
+These linters can be easily integrated into IDEs such as RubyMine or VS Code.
+
+For VS Code, just install the basic Ruby extension which handles Rubocop ([`rebornix.ruby`](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby)) and the official Sorbet one ([`sorbet.sorbet-vscode-extension`](https://marketplace.visualstudio.com/items?itemName=sorbet.sorbet-vscode-extension)).
+
+Recommended settings:
+```json
+{
+    "editor.formatOnSave": true,
+    "ruby.useBundler": true,
+    "ruby.lint": {
+        "rubocop": {
+            "useBundler": true, // enable rubocop via bundler
+        }
+    },
+    "ruby.format": "rubocop",
+    "ruby.useLanguageServer": true,
+    "sorbet.enabled": true
+}
+```
+
+### Commit message convention
+
+This repository follows a commit message convention in order to automatically generate the [CHANGELOG](./CHANGELOG.md). Make sure you follow the rules of [conventional commits](https://www.conventionalcommits.org/) when opening a pull request.
+
+### Releasing a new version (for Stream developers)
+
+In order to release new version you need to be a maintainer of the library.
+
+- Kick off a job called `initiate_release` ([link](https://github.com/GetStream/stream-chat-ruby/actions/workflows/initiate_release.yml)).
+
+The job creates a pull request with the changelog. Check if it looks good.
+
+- Merge the pull request.
+
+Once the PR is merged, it automatically kicks off another job which will upload the Gem to RubyGems.org and creates a GitHub release.

README.md

@@ -1,57 +1,64 @@
-# stream-chat-ruby
+# Official Ruby SDK for [Stream Chat](https://getstream.io/chat/)
 
 [![build](https://github.com/GetStream/stream-chat-ruby/workflows/build/badge.svg)](https://github.com/GetStream/stream-chat-ruby/actions) [![Gem Version](https://badge.fury.io/rb/stream-chat-ruby.svg)](http://badge.fury.io/rb/stream-chat-ruby)
 
-stream-chat-ruby is the official Ruby client for [Stream chat](https://getstream.io/chat/) a service for building chat applications.
+<p align="center">
+    <img src="./assets/logo.svg" width="50%" height="50%">
+</p>
+<p align="center">
+    Official Ruby API client for Stream Chat, a service for building chat applications.
+    <br />
+    <a href="https://getstream.io/chat/docs/"><strong>Explore the docs »</strong></a>
+    <br />
+    <br />
+    <a href="https://github.com/GetStream/rails-chat-example">Code Samples</a>
+    ·
+    <a href="https://github.com/GetStream/stream-chat-ruby/issues">Report Bug</a>
+    ·
+    <a href="https://github.com/GetStream/stream-chat-ruby/issues">Request Feature</a>
+</p>
 
-You can sign up for a Stream account at https://getstream.io/chat/get_started/.
+## 📝 About Stream
 
-You can use this library to access chat API endpoints server-side. For the
-client-side integrations (web and mobile) have a look at the JavaScript, iOS and
-Android SDK libraries (https://getstream.io/chat/).
+You can sign up for a Stream account at our [Get Started](https://getstream.io/chat/get_started/) page.
 
-### Installation
+You can use this library to access chat API endpoints server-side.
 
-stream-chat-ruby supports:
+For the client-side integrations (web and mobile) have a look at the JavaScript, iOS and Android SDK libraries ([docs](https://getstream.io/chat/)).
 
-- Ruby (2.5, 2.6, 2.7, 3.0, 3.1)
+## ⚙️ Installation
+
+[`stream-chat-ruby`](https://rubygems.org/gems/stream-chat-ruby) supports:
 
-#### Install
+- Ruby (2.5, 2.6, 2.7, 3.0, 3.1)
 
 ```bash
-gem install stream-chat-ruby
+$ gem install stream-chat-ruby
 ```
 
-### Documentation
-
-[Official API docs](https://getstream.io/chat/docs/)
-
-### Supported features
-
-- Chat channel type, channels and members
-- Messages
-- User management
-- Moderation API
-- Push configuration
-- User devices
-- User search
-- Channel search
-- Blocklists
-- Export channels
-
-### Import
+## ✨ Getting started
 
 ```ruby
 require 'stream-chat'
-```
 
-### Initialize client
-
-```ruby
 client = StreamChat::Client.new(api_key='STREAM_KEY', api_secret='STREAM_SECRET')
 ```
 
-### Generate a token for client side use
+> 💡 Note: since v2.21.0 we implemented [Sorbet](https://sorbet.org/) type checker. As of v2.x.x we only use it for static type checks and you won't notice any difference, but from v3.0.0 **we will enable runtime checks** 🚨 🚨 🚨.
+
+> What this means, is that you'll receive an error during runtime if you pass an invalid type to our methods. To prepare for that, just make sure whatever you pass in, matches the method signature (`sig { ... }`).
+ 
+---
+
+> Additionally, in a future major version, we would like to enforce symbol hash keys during runtime to conform to Ruby best practises. It's a good idea to prepare your application for that.
+> ```ruby
+> # Wrong:
+> user = { "user" => { "id" => "bob-1"}}
+> # Correct:
+> user = { :user => { :id => "bob-1" }}
+> ```
+
+### Generate a token for client-side usage:
 
 ```ruby
 client.create_token('bob-1')
@@ -66,125 +73,90 @@ client.update_user({
     :name => 'Robert Tables'
 })
 
-# batch update is also supported
-jane = ...
-june = ...
+# Batch update is also supported
+jane = {:id => 'jane-1'}
+june = {:id => 'june-1'}
 client.update_users([jane, june])
 ```
 
-### Channel types CRUD
+### Channel types
 
 ```ruby
-# Create
 client.create_channel_type({
-    'name' => 'livechat',
-    'automod' => 'disabled',
-    'commands' => ['ban'],
-    'mutes' => true
+    :name => 'livechat',
+    :automod => 'disabled',
+    :commands => ['ban'],
+    :mutes => true
 })
 
-# Update
-client.update_channel_type('livechat', 'automod' => 'enabled'})
-
-# Get
-client.get_channel_type('livechat')
-
-# List
-client.list_channel_types
-
-# Delete
-client.delete_channel_type('livechat')
+channel_types = client.list_channel_types()
 ```
 
 ### Channels
 
 ```ruby
 # Create a channel with members from the start
-chan = client.channel("messaging", channel_id: "bob-and-jane", data: {'members'=> ['bob-1', 'jane-77']})
+chan = client.channel("messaging", channel_id: "bob-and-jane", data: {:members => ['bob-1', 'jane-77']})
 chan.create('bob-1')
 
 # Create a channel and then add members
 chan = client.channel("messaging", channel_id: "bob-and-jane")
 chan.create('bob-1')
 chan.add_members(['bob-1', 'jane-77'])
+```
 
-# Send messages
-m1 = chan.send_message({'text' => 'Hi Jane!'}, 'bob-1')
-m2 = chan.send_message({'text' => 'Hi Bob'}, 'jane-77')
-
-# Send replies
-r1 = chan.send_message({'text' => 'And a good day!', 'parent_id' => m1['id']}, 'bob-1')
-
-# Send reactions
-chan.send_reaction(m1['id'], {'type' => 'like'}, 'bob-1')
+### Reactions
+```ruby
+chan.send_reaction(m1['id'], {:type => 'like'}, 'bob-1')
+```
 
-# Add/remove moderators
+### Moderation
+```ruby
 chan.add_moderators(['jane-77'])
 chan.demote_moderators(['bob-1'])
 
-# Add a ban with a timeout
 chan.ban_user('bob-1', timeout: 30)
 
-# Remove a ban
 chan.unban_user('bob-1')
-
-# Query channel state
-chan.query({'messages' => { 'limit' => 10, 'id_lte' => m1['id']}})
-
-# Update metadata (overwrite)
-chan.update({'motd' => 'one apple a day....'})
-
-# Update partial
-# 1. key-value pairs to set
-# 2. keys to unset (remove)
-chan.update_partial({color: 'blue', age: 30}, ['motd'])
-
-# Query channel members
-chan.query_members({name: {'$autocomplete': 'test'}}, sort: {last_created_at: -1}, offset: 5, limit: 5)
 ```
 
 ### Messages
 
 ```ruby
-# Delete a message from any channel by ID
+m1 = chan.send_message({:text => 'Hi Jane!'}, 'bob-1')
+
 deleted_message = client.delete_message(r1['id'])
 
 ```
 
 ### Devices
 
 ```ruby
-# Add device
-jane_phone = client.add_device({'id' => 'iOS Device Token', 'push_provider' => push_provider.apn, 'user_id' => 'jane-77'})
+jane_phone = client.add_device({:id => 'iOS Device Token', :push_provider => push_provider.apn, :user_id => 'jane-77'})
 
-# List devices
 client.get_devices('jane-77')
 
-# Remove device
 client.remove_device(jane_phone['id'], jane_phone['user_id'])
 ```
 
 ### Blocklists
 
 ```ruby
-# Create a blocklist
 client.create_blocklist('my_blocker', %w[fudge cream sugar])
 
-# Enable it on messaging channel type
+# Enable it on 'messaging' channel type
 client.update_channel_type('messaging', blocklist: 'my_blocker', blocklist_behavior: 'block')
 
-# Get the details of the blocklist
 client.get_blocklist('my_blocker')
 
-# Delete the blocklist
 client.delete_blocklist('my_blocker')
 ```
 
 ### Export Channels
 
 ```ruby
 # Register an export
-response = client.export_channels({type: 'messaging', id: 'jane'})
+response = client.export_channels({:type => 'messaging', :id => 'jane'})
 
 # Check completion
 status_response = client.get_export_channel_status(response['task_id'])
@@ -204,33 +176,13 @@ limits = client.get_rate_limits(server_side: true)
 limits = client.get_rate_limits(android: true, ios: true, endpoints: ['QueryChannels', 'SendMessage'])
 ```
 
-### Example Rails application
-
-See [an example rails application using the Ruby SDK](https://github.com/GetStream/rails-chat-example).
-
-### Contributing
-
-First, make sure you can run the test suite. Tests are run via rspec
-
-```bash
-STREAM_KEY=my_api_key STREAM_SECRET=my_api_secret bundle exec rake spec
-```
-
-This repository follows a commit message convention in order to automatically generate the [CHANGELOG](./CHANGELOG.md). Make sure you follow the rules of [conventional commits](https://www.conventionalcommits.org/) when opening a pull request.
-
-### Releasing a new version
-
-In order to release new version you need to be a maintainer of the library.
-
-- Kick off a job called `initiate_release` ([link](https://github.com/GetStream/stream-chat-ruby/actions/workflows/initiate_release.yml)).
-
-The job creates a pull request with the changelog. Check if it looks good.
+## ✍️ Contributing
 
-- Merge the pull request.
+We welcome code changes that improve this library or fix a problem, please make sure to follow all best practices and add tests if applicable before submitting a Pull Request on Github. We are very happy to merge your code in the official repository. Make sure to sign our [Contributor License Agreement (CLA)](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform) first. See our [license file](./LICENSE) for more details.
 
-Once the PR is merged, it automatically kicks off another job which will upload the Gem to RubyGems.org and creates a GitHub release.
+Head over to [CONTRIBUTING.md](./CONTRIBUTING.md) for some development tips.
 
-## We are hiring!
+## 🧑‍💻 We are hiring!
 
 We've recently closed a [$38 million Series B funding round](https://techcrunch.com/2021/03/04/stream-raises-38m-as-its-chat-and-activity-feed-apis-power-communications-for-1b-users/) and we keep actively growing.
 Our APIs are used by more than a billion end-users, and you'll have a chance to make a huge impact on the product within a team of the strongest engineers all over the world.

assets/logo.svg

@@ -14,7 +14,7 @@ Gem::Specification.new do |gem|
   gem.homepage = 'http://github.com/GetStream/stream-chat-ruby'
   gem.authors = ['getstream.io']
   gem.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|sorbet|spec|\.github|scripts)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|sorbet|spec|\.github|scripts|assets)/}) }
   end
   gem.required_ruby_version = '>=2.5.0'
   gem.metadata = {