docs: add contributor documentation & automated conventional commit c…

…heck (#1511)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,50 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: 'bug:'
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+
+If applicable, add screenshots to help explain your problem.
+
+**Package version**
+- stream-chat-react:
+- stream-chat-css:
+- stream-chat-js:
+
+**Desktop (please complete the following information):**
+
+- OS: [e.g. iOS]
+- Browser [e.g. chrome, safari]
+- Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+
+- Device: [e.g. iPhone6]
+- OS: [e.g. iOS8.1]
+- Browser [e.g. stock browser, safari]
+- Version [e.g. 22]
+
+**Additional context**
+
+Add any other context about the problem here.

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to stream-chat-react
+
+As a contributor, here are the guidelines we would like you to follow:
+
+- [Asking questions](#asking-questions)
+- [Filing an issue](#filing-an-issue)
+- [Contribution Standards](#coding-standards)
+- [Submission Guidelines](#submission-guidelines)
+- [Signing the CLA](#contributor-licence-agreement)
+
+
+## <a name="asking-questions"></a>Are you looking for answers?
+There are many ways you can get your questions answered. It can be hard to decide, where to begin if you are just starting out. We suggest you take a look at the resources in the following order:
+
+### 1. Stream chat API documentation
+Package `stream-chat-react`  has a peer dependency [stream-chat-js](https://github.com/GetStream/stream-chat-js) - a client library for interacting with the Stream Chat API (see the [API docs](https://getstream.io/chat/docs/javascript/?language=javascript)).
+
+### 2. Documentation for stream-chat-react
+The [stream-chat-react](https://getstream.io/chat/docs/sdk/react/) documentation is held separately from the Stream Chat API docs. Besides documenting the component API, it provides examples of their use in various scenarios.
+
+### 3. Read the source code
+When you plan on contributing to the repository try to get acquainted with the existing code base. The best way to learn :)
+
+### 4. Take a look at our tutorials
+
+
+### Get help from our Customer Success team
+If what you are looking for is technical support embedding Stream in your application, we suggest emailing our Customer Success team at [email protected] with your application key and the SDK versions you're using. The Issue section of this GitHub repo is now reserved only for bug reports, feature improvements and suggestions.
+
+
+## <a name="filing-an-issue"></a>Filing an issue
+Spotting imperfections and not keeping them to yourself is the first step to make this library better. We are very grateful for reports concerning imperfections in the source code or the [documentation]((https://getstream.io/chat/docs/sdk/react/)). Before filing an issue, please, review the list of [open issues](https://github.com/GetStream/stream-chat-react/issues) first.
+
+### Reporting bugs
+You can report a source code bug by using the [Bug Report template](https://github.com/GetStream/stream-chat-react/issues/new/choose). Make sure you include "steps to reproduce" section. Bug that cannot be reproduced cannot be solved.
+
+Do not be afraid to report imperfections in our [documentation]((https://getstream.io/chat/docs/sdk/react/)) as well. In such case, please attach the `docs` tag to the issue.
+
+
+### Requesting a feature
+You can request a feature by submitting a [Feature request issue](https://github.com/GetStream/stream-chat-react/issues/new?assignees=&labels=feature&template=feature_request.md&title=) in our repository. If you would like to implement the proposal, please state it in the issue. It will allow us to discuss the proposal and better coordinate the efforts. You can even ping us - mention `@GetStream/stream-react-developers ` in the issue.
+
+## <a name="contribution-standards"></a> Contributing to the repo
+
+### Set up for success
+It is always good to get acquainted with the specifics of the package. For example the `stream-chat-react` package has its peer dependencies (`stream-chat-js`, `stream-chat-css`), which you may need to tweak at the same time, while developing the feature for `stream-chat-react`. To get more into those specifics, please read [development guide](./developers/DEVELOPMENT.md).
+
+### Good first issue
+
+###<a name="#coding-rules"></a> Coding rules
+Any contributions to the library should follow Stream's coding rules.
+
+#### 1. Code should be tested
+All the code submitted should be covered by unit tests. Mocking utilities are provided in `src/mock-builders`. Optimally a suite of E2E tests should be included as well.
+
+#### 2. API Changes should be documented
+Changes to components interface exposed to the library integrators should be documented. We keep the documentation `docusaurus/docs/React` folder.
+
+#### 3. Code should be DRY & correctly formatted
+If you find yourself copying source code from one place to another, please extract it into a separate component or function.
+
+#### 4. Keep an eye on performance
+Keep in mind that the chat application may need to work with thousands of messages.
+
+#### 5. Follow commit formatting rules
+We follow [Angular's Commit Message Format rules](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format) with [possible deviations](./developers/COMMIT.md). The same rules are used by our release automation tool. Therefore, every commit message should strictly comply with these rules.
+
+
+## <a name="submission-guidelines"></a> Submitting your work
+1. Make sure you have signed our Contributor License agreement
+2. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) the repo and create a dedicated git branch locally
+3. Follow the [coding rules](#coding-rules)
+4. Create a descriptive PR ([see more on PR requirements](./developers/PR_REVIEW.md))
+
+
+## <a name="contributor-licence-agreement"></a> Contributor License Agreement
+Before we can merge your contribution into our repository, we would like to ask you to sign the [Contributor License Agreement](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform).
+

commitlint.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional']
+};

developers/BRANCHES.md

@@ -0,0 +1,20 @@
+# Branches
+We have 2 protected (base) branches:
+
+- `develop`
+- `master`
+
+If you want to implement a solution, you are required to create branches from `develop` or its derivatives.
+
+The `develop` branch serves as a reservoir of bug fixes and new features waiting to be released.
+
+The `master` branch serves for release and should receive updates only from the `develop` branch.
+
+So the branch architecture in this repository is as follows:
+
+```shell
+NPM <--- master <--- develop <--- branch_solution_x
+                             <--- branch_solution_y
+                             <--- branch_solution_x
+                             ...
+```

developers/COMMIT.md

@@ -0,0 +1,23 @@
+We follow [Angular's Commit Messag Format rules](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format). Even though these are curated sets of rules, the following represent our additions to them:
+
+## Commit message type
+
+The commit type makes up the first part of the commit header:
+
+```shell
+<type>(<scope>): <short summary>
+```
+
+It must be one of the following:
+
+* **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
+* **chore**: Changes that do not relate to a fix or feature and don't modify source or test files (for example updating dependencies)
+* **ci**: Changes to our CI configuration files and scripts (examples: CircleCi, SauceLabs)
+* **docs**: Documentation only changes
+* **feat**: A new feature
+* **fix**: A bug fix
+* **perf**: A code change that improves performance
+* **revert**: Reverts a previous commit
+* **refactor**: A code change that neither fixes a bug nor adds a feature
+* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+* **test**: Adding missing tests or correcting existing tests

developers/DEVELOPMENT.md

@@ -0,0 +1,34 @@
+## 1. Set yourself up
+If you are solving issues, that require adjustments in CSS or Stream Chat API client, then you want to fork the following repositories:
+
+- `stream-chat-react`
+- `stream-chat-css`
+- `stream-chat-js`
+
+
+GitHub provides guides on how to [fork and contribute to projects](https://docs.github.com/en/get-started/quickstart/contributing-to-projects).
+
+## 2. Link the peer dependencies
+If you are doing changes in peer dependencies and you want to see them reflected in a running application, you will need to [create symbolic links](https://classic.yarnpkg.com/en/docs/cli/link) to those repositories on your disk (`yarn link` in peer dependency's root folder --> `yarn link dep_name` in `stream-chat-react` root folder). No need to tweak `package.json` manually.
+
+## 3. Create a new branch
+Please create a new branch from the freshly pulled `develop` branch. We keep a simple [system of branches](./BRANCHES.md).
+
+## 4. Write your code
+Please follow our [Coding rules](../CONTRIBUTING.md#coding-rules). You can start by designing the user journeys by writing E2E tests.
+
+## 4. Run your code
+Again, if you are doing changes in peer dependencies, run `yarn start`:
+1. in their root folders as well as
+2. in the root folder of the `stream-chat-react` package.
+
+Then you can start one of the applications in the `examples` folder. We recommend you to run the [`typescript` app](../examples/typescript).
+
+## 5. Push your changes and create a PR
+You are almost done. Please do not underestimate the role of a [well-prepared PR](./PR.md).
+
+## 6. Fix imperfections
+It can happen that the PR reviewer asks you to fix imperfections in your implementation. Please make adjustments agreed with the PR reviewer and push them back upstream.
+
+## 7. Once the PR is merged
+You can delete the local copy of your branch. Well done!

developers/E2E.md

@@ -0,0 +1,18 @@
+note: this document is a WIP
+
+# E2E tests
+
+End-to-end tests are a great mean of:
+- quality assurance
+- feature documentation
+
+They play a crucial role in communicating the expected behavior and interaction between the components. E2E test suites are great for documenting the user journeys - a good start to developing a given feature.
+
+ Our E2E tests live in the [`e2e` folder](./e2e). They rely on so-called stories located in [`src/stories` folder](./src/components). E2E tests are run with the combination of [ladle](https://www.ladle.dev/) (utility used for documenting our components in form of stories) and [playwright](https://playwright.dev/) (E2E test runner).
+
+To run the E2E tests you need to:
+
+1. Create your Stream chat application in the [Stream Dashboard](https://dashboard.getstream.io/) (we recommend you to use a dedicated app).
+2. Create a `.env` file in the repository's root directory with env variable names corresponding to those in [`.env.example` file](./.env.example).
+3. Populate channels with messages in your chat application running the fixtures script `yarn e2e-fixtures`
+4. Run E2E tests with `yarn e2e` script

developers/PR.md

@@ -0,0 +1,65 @@
+
+## Creating PR
+To [create a PR](https://docs.github.com/en/enterprise-cloud@latest/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request), we use a [PR template](../PULL_REQUEST_TEMPLATE.md) `PULL_REQUEST_TEMPLATE.md`. It consists of 3 sections:
+
+1. [🎯 Goal](#goal) *(mandatory)*
+2. [🛠 Implementation details](#implementation-details) *(recommended)*
+3. [🎨 UI Changes](#ui-changes) *(optional)*
+4. [References](#references) *(mandatory if exist)*
+
+#### <a name="goal"></a>🎯 Goal
+High level description on what is changing and what benefits do the change bring. Without
+
+#### <a name="implementation-details"></a>🛠 Implementation details
+Should include an explanation of the logic applied to solving the problem. It provides a context that will make the review much easier.
+
+#### <a name="ui-changes"></a>🎨 UI Changes
+This is a great place to showcase:
+
+- screenshots of “before” and “after”
+- short videos demonstrating user interaction (“before” and “after”)
+
+A good way to keep this section readable is to [include collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
+
+#### References
+If the PR solves one or more previously filed issues, then it should contain one reference per each issue - [link the issues](https://docs.github.com/en/enterprise-cloud@latest/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
+
+It may often be the case, that you are implementing a feature with changes in styling ([`stream-chat-css`](https://github.com/GetStream/stream-chat-css)) or Stream Chat API client (`stream-chat-js`). Those PRs may contain changes on which depends the functionality of the currently created PR in `stream-chat-react`. In such case, you should include references to PRs in those repos as well (e.g. `Depends on https://github.com/GetStream/stream-chat-css/issues/66`).
+
+Create PRs to be merged into branches other than the `master` branch (i.e. `develop` or other).
+
+Each PR should be assigned to least one reviewer from the [Stream React Developers group](https://github.com/orgs/GetStream/teams/stream-react-developers/members).
+
+## PR review
+
+The review should verify that the contributor has delivered a complete solution. If a PR has linked one or more well-documented issues, then the reviewer can rely on acceptance criteria listed there. Another source of context information for the reviewer may be the PR sections [🛠 Implementation details](#implementation-details) or [🎨 UI Changes](#ui-changes). If you are not satisfied with the inputs provided, ask for their addition.
+
+Having a good context, the reviewer can then check that the source code follows the [Coding rules](../CONTRIBUTING.md#coding-rules) as well as is free of bugs by executing the following steps:
+
+1. read the changed source code
+2. review the added unit tests for completeness
+3. review the [E2E tests'](../e2e) scenarios for their completeness
+4. review the changes in the documentation
+5. build, run and click through the example application locally (
+   - are there some regression bugs?
+   - are there all changes claimed in the PR and do they work as documented?
+   - do the changes have impact on app performance?
+   - are there any errors in the browser console?
+
+The PR should be returned for rework if any of the steps stumble upon shortcomings in regard to the [Coding rules](../CONTRIBUTING.md#coding-rules).
+
+### Usual scenarios to click through
+
+- Add a message to the channel message list and to a thread (text message, file upload, image upload, audio file upload, giphy)
+- Update, delete a message in the channel message list and in a thread (text message, file upload, image upload, audio file upload, giphy)
+- Messages are loaded while scroll through the message list
+- Add a new message while scrolled up not seeing the latest messages (should be automatically scrolled to the latest message)
+- Receive a new message while scrolled up not seeing the latest messages (a new message notification should appear)
+- Reactions to messages in the channel message list and in the thread (add emoji, quote, pin, start thread)
+- Change channel
+- Load more channels in the channel list
+
+## Merging the PR
+
+PRs should be squash-merged in order to keep the git history clean. The resulting commit message should follow the [Angular's Commit Messag Format rules](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format).
+

developers/RELEASE.md

@@ -0,0 +1,31 @@
+# Release
+The `stream-chat-react` package follows semantic versioning and the release is to a big part automated by `semantic-release`. The utility automates:
+
+1. Collects release notes from the commits added since the last release
+2. Creates a [GitHub release](https://github.com/GetStream/stream-chat-react/releases)
+3. Appends release notes to `CHANGELOG.md`
+4. Publishes a new package version to NPM.
+
+In order the above generates correct outputs, each contributor should [Angular's Commit Messag Format rules](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format).
+
+At the moment these manual actions have to be taken while doing a release:
+
+0. Make sure that all the new required features and bug fixes in peer dependency repositories `@stream-io/stream-chat-css` and `stream-chat-js` are released
+1. Make sure that the peer dependencies `@stream-io/stream-chat-css` and `stream-chat-js` are installed at their latest version (see `package.json`, `yarn.lock`)
+2. Create a new PR request from `develop` to `master` branch.
+   - The PR name should correspond to the next package version that is to be released (e.g. v1.1, v8, v9.1.2). You can use GitHub's CLI utility (e.g. `gh pr create —base master`)
+   - The PR description should list all the changes in form of commit messages (therefore we require squashing the commit history when merging into `develop`).
+3. Solve potential conflicts between the two branches
+   - As `master` receives updates only from `develop`, there should be no conflicts.
+4. Merge the PR and make sure that:
+   - the `CHANGELOG.md` file has been correctly updated
+   - a new (correct) version of the package has been published at NPM
+   - a new release with correct version number has be created in GitHub
+
+## After the release
+We maintain multiple demo applications developed with `stream-chat-react`. With each new version of the package, the applications should have their dependencies upgraded explicitly in their `package.json`.
+
+The demo apps repositories are:
+
+- GetStream/website-react-examples
+- GetStream/watercooler

dotgit/hooks/pre-commit-reject-binaries.py

@@ -6,7 +6,7 @@
 # from https://gist.github.com/LukasKnuth/1839424
 """
 This is a git commit-hook which can be used to check if huge files
- where accidentally added to the staging area and are about to be
+ were accidentally added to the staging area and are about to be
  committed.
 If there is a file which is bigger then the given "max_file_size"-
  variable, the script will exit non-zero and abort the commit.

package.json

@@ -77,6 +77,8 @@
     "@babel/preset-env": "^7.12.7",
     "@babel/preset-react": "^7.12.7",
     "@babel/preset-typescript": "^7.12.7",
+    "@commitlint/cli": "^16.2.3",
+    "@commitlint/config-conventional": "^16.2.1",
     "@ladle/react": "^0.8.5",
     "@playwright/test": "^1.20.0",
     "@rollup/plugin-babel": "^5.2.1",
@@ -173,7 +175,8 @@
   },
   "husky": {
     "hooks": {
-      "pre-commit": "dotgit/hooks/pre-commit-format.sh && dotgit/hooks/pre-commit-reject-binaries.py"
+      "pre-commit": "dotgit/hooks/pre-commit-format.sh && dotgit/hooks/pre-commit-reject-binaries.py",
+      "commit-msg": "npx commitlint --edit $1"
     }
   },
   "scripts": {