Merge remote-tracking branch 'origin/next' into switch-to-ts

Author: phryneas

README.md

@@ -17,25 +17,12 @@
     <img src="https://badgen.net/npm/dm/react-async" alt="montly downloads">
   </a>
   <a href="https://bundlephobia.com/result?p=react-async">
-    <img src="https://badgen.net/bundlephobia/min/react-async" alt="minified size">
+    <img src="https://badgen.net/bundlephobia/minzip/react-async" alt="minzipped size">
   </a>
   <a href="https://opensource.org/licenses/ISC">
     <img src="https://badgen.net/npm/license/react-async" alt="license">
   </a>
   <br/>
-  <a href="https://github.com/async-library/react-async/issues">
-    <img src="https://badgen.net/github/open-issues/async-library/react-async?icon=github" alt="issues">
-  </a>
-  <a href="https://github.com/async-library/react-async/pulls">
-    <img src="https://badgen.net/github/open-prs/async-library/react-async?icon=github" alt="pull requests">
-  </a>
-  <a href="https://github.com/async-library/react-async/releases">
-    <img src="https://badgen.net/github/releases/async-library/react-async?icon=github" alt="releases">
-  </a>
-  <a href="https://github.com/async-library/react-async/graphs/contributors">
-    <img src="https://badgen.net/github/contributors/async-library/react-async?icon=github" alt="contributors">
-  </a>
-  <br/>
   <a href="https://circleci.com/gh/async-library/react-async">
     <img src="https://badgen.net/circleci/github/async-library/react-async/master?icon=circleci" alt="circleci status">
   </a>
@@ -52,10 +39,6 @@
     <img src="https://deepscan.io/api/teams/5549/projects/7406/branches/74183/badge/grade.svg" alt="DeepScan grade">
   </a>
   <br/>
-  <img src="https://badgen.net/david/dep/async-library/react-async/packages/react-async" alt="dependencies">
-  <img src="https://badgen.net/david/dev/async-library/react-async" alt="devDependencies">
-  <img src="https://badgen.net/david/peer/async-library/react-async/packages/react-async" alt="peerDependencies">
-  <br/>
   <a href="https://discord.gg/CAYQ6mU">
     <img src="https://img.shields.io/badge/discord-join-7289DA.svg?logo=discord&longCache=true&style=flat" />
   </a>
@@ -120,6 +103,14 @@ Use it with `fetch`, Axios or other data fetching libraries, even GraphQL.
 - [Optimistic updates](https://docs.react-async.com/guide/optimistic-updates)
 - [Server-side rendering](https://docs.react-async.com/guide/server-side-rendering)
 
+## Contributing
+
+- [Introduction](https://docs.react-async.com/contributing/introduction)
+- [Setting up](https://docs.react-async.com/contributing/setting-up)
+- [Development](https://docs.react-async.com/contributing/development)
+- [Testing](https://docs.react-async.com/contributing/testing)
+- [Releasing](https://docs.react-async.com/contributing/releasing)
+
 # Contributors
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -162,3 +153,11 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+
+## Similar projects
+
+- [@slorber/react-async-hook](https://github.com/slorber/react-async-hook)
+- [@dai-shi/react-hooks-async](https://github.com/dai-shi/react-hooks-async)
+- [@cristovao-trevisan/async-resource](https://github.com/cristovao-trevisan/async-resource)
+- [@ilyalesik/react-fetch-hook](https://github.com/ilyalesik/react-fetch-hook)
+- [@marcin-piela/react-fetching-library](https://github.com/marcin-piela/react-fetching-library)

docs/_summary.md

@@ -23,3 +23,11 @@
 - [Async actions](guide/async-actions.md)
 - [Optimistic updates](guide/optimistic-updates.md)
 - [Server-side rendering](guide/server-side-rendering.md)
+
+## Contributing
+
+- [Introduction](contributing/introduction.md)
+- [Setting up](contributing/setting-up.md)
+- [Development](contributing/development.md)
+- [Testing](contributing/testing.md)
+- [Releasing](contributing/releasing.md)

docs/contributing/development.md

@@ -0,0 +1,45 @@
+# Development
+
+React Async is a library without visual parts. Only the DevTools have a user interface you can spin up in a browser.
+Therefore the development workflow for the core library might be different from what you're used to. Generally, we use a
+TDD approach:
+
+- Write a unit test for the new feature or bug you want to fix. Sometimes you can just extend an existing test.
+- Fix the test by implementing the feature or bugfix. Now all tests should pass.
+- Optionally refactor the code for performance, readability and style. Probably this will come up during PR review.
+
+We use the GitHub pull request workflow. In practice this means your workflow looks like this:
+
+- Fork the repo (or pull the latest upstream) under your own account.
+- Make your changes, commit and push them. We don't enforce any commit message format.
+- Open a pull request on the main repository against the `next` branch. Make sure to follow the template.
+- We'll review your PR and will probably ask for some changes.
+- Once ready, we'll merge your PR.
+- Your changes will be in the next release.
+
+## Working with Storybook
+
+We use Storybook as a development environment for the DevTools. Spin it up using:
+
+```sh
+yarn start:storybook
+```
+
+This should open up Storybook in a browser at http://localhost:6006/
+Run it side-by-side with `yarn test --watch` during development. See [Testing](#testing).
+
+## Working with the examples
+
+In the `examples` folder, you will find sample React applications that use React Async in various ways with various other libraries. Please add a new example when introducing a major new feature. Make sure to add it to `now.json` so it is automatically deployed when merged to `master`.
+
+To run sample examples on your local environments
+
+```sh
+yarn build:examples
+yarn test:examples
+yarn start:examples
+```
+
+## Resolving issues
+
+Sometimes your dependencies might end up in a weird state, causing random issues, especially when working with the examples. In this case it often helps to run `yarn clean -y && yarn bootstrap`. This will delete `node_modules` from all packages/examples and do a clean install.

docs/contributing/introduction.md

@@ -0,0 +1,92 @@
+# Contributing to React Async
+
+Thanks for your interest in improving React Async! Contributions of any kind are welcome. Please refer to this guide before opening an issue or pull request.
+
+This repo relies on Yarn workspaces, so you should [install](https://yarnpkg.com/en/docs/install) and use `[email protected]` or higher as the package manager for this project.
+
+## Development guide
+
+Please have the **_latest_** stable versions of the following on your machine
+
+- node
+- yarn
+
+### Initial setup
+
+To start working on React Async, clone the repo and bootstrap the project:
+
+```sh
+git clone https://github.com/async-library/react-async.git
+cd react-async
+yarn && yarn bootstrap && yarn test
+```
+
+Note that all work is done against the `next` branch, we only merge to `master` when doing a release.
+
+### Working with Storybook
+
+We use Storybook as a development environment, particularly for the DevTools. Spin it up using:
+
+```sh
+yarn start:storybook
+```
+
+This should open up Storybook in a browser at http://localhost:6006/
+Run it side-by-side with `yarn test --watch` during development. See [Testing](#testing).
+
+### Linting
+
+Use `yarn lint` to verify your code style before committing. It's highly recommended to install the Prettier and ESLint plugins for your IDE. Travis CI will fail your build on lint errors. Configure VS Code with the following settings:
+
+```plaintext
+"eslint.autoFixOnSave": true,
+"eslint.packageManager": "yarn",
+"eslint.options": {
+  "cache": true,
+  "cacheLocation": ".cache/eslint",
+  "extensions": [".js", ".jsx", ".mjs", ".json", ".ts", ".tsx"]
+},
+"eslint.validate": [
+  "javascript",
+  "javascriptreact",
+  {"language": "typescript", "autoFix": true },
+  {"language": "typescriptreact", "autoFix": true }
+],
+"eslint.alwaysShowStatus": true
+```
+
+This should enable auto-fix for all source files, and give linting warnings and errors within your editor.
+
+### Testing
+
+Use the following command to test all packages in watch mode. Refer to the [Jest CLI options](https://jestjs.io/docs/en/cli#options) for details.
+
+```sh
+yarn test:watch
+```
+
+In general, this is sufficient during development. Travis CI will apply a more rigorous set of tests.
+
+#### Testing for compatibility
+
+```sh
+yarn test:compat
+```
+
+This runs all tests using various versions of `react` and `react-dom`, to check for compatibility with older/newer versions of React. This is what CircleCI and Travis run.
+
+### Working with the examples
+
+In the `examples` folder, you will find sample React applications that use React Async in various ways with various other libraries. Please add a new example when introducing a major new feature. Make sure to add it to `now.json` so it is automatically deployed when merged to `master`.
+
+To run sample examples on your local environments
+
+```sh
+yarn build:examples
+yarn test:examples
+yarn start:examples
+```
+
+### Resolving issues
+
+Sometimes your dependencies might end up in a weird state, causing random issues, especially when working with the examples. In this case it often helps to run `yarn clean -y && yarn bootstrap`. This will delete `node_modules` from all packages/examples and do a clean install.

docs/contributing/releasing.md

@@ -0,0 +1,24 @@
+# Releasing
+
+All ongoing development is done on the `next` branch. When preparing for a release, we'll create a `release` branch
+which will eventually be merged into `master`. This way, what's on `master` is always what's published on `npm`.
+
+Release management is currently a manual process, to be performed by core team members only. Here's the process:
+
+1. Create a `release` branch, usually based on `next`.
+2. Open a pull request for `release` -> `master`
+3. Write the release notes in the PR description.
+4. Run `yarn bump` to increment the version number. Take care to follow semver.
+5. Tag the release with `git tag vX.X.X` (using the correct version number).
+6. Push the release commit AND tag: `git push --follow-tags`
+7. Publish each package (in `./packages`) to npm using the script below.
+8. Create a new release on GitHub and copy the release notes there.
+
+```
+cd packages/react-async
+npm publish pkg
+cd ../react-async-devtools
+npm publish pkg
+```
+
+Take care to publish the `pkg` directory!

docs/contributing/setting-up.md

@@ -0,0 +1,61 @@
+# Setting up your development environment
+
+## Prerequisites
+
+In order to develop React Async on your local machine, you'll need `git`, `node` and `yarn`.
+
+### Git
+
+To clone the repository, commit your changes and push them upstream, you'll need to have `git` [installed][install git].
+
+[install git]: https://www.atlassian.com/git/tutorials/install-git
+
+### Node.js
+
+As a JavaScript project, we rely heavily on Node.js. It's recommended to use a version manager such as [fnm] for Mac /
+Linux or [nvm-windows] for Windows to install the latest Node.js with.
+
+[fnm]: https://github.com/Schniz/fnm
+[nvm-windows]: https://github.com/coreybutler/nvm-windows
+
+### Yarn
+
+This repo relies on Yarn workspaces, so you should [install][install yarn] and use `[email protected]` or higher as the package
+manager for this project.
+
+[install yarn]: https://yarnpkg.com/en/docs/install
+
+## Project setup
+
+To start working on React Async, clone the repository and bootstrap the project by running the following commands
+one-by-one:
+
+```sh
+git clone https://github.com/async-library/react-async.git
+cd react-async
+yarn install
+yarn bootstrap
+yarn test
+```
+
+This should install all dependencies, build and link the react-async and react-async-devtools packages to the examples,
+and finally run the unit tests. In the end it should succeed with a message (numbers may change):
+
+```
+Test Suites: 6 passed, 6 total
+Tests:       136 passed, 136 total
+```
+
+> Note that all work is done against the `next` branch, we only merge to `master` when doing a release.
+
+## Editor setup
+
+We recommend using [Visual Studio Code](https://code.visualstudio.com/) with the following extensions:
+
+- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
+- [DeepScan](https://marketplace.visualstudio.com/items?itemName=DeepScan.vscode-deepscan)
+- [Oceanic Plus](https://marketplace.visualstudio.com/items?itemName=marcoms.oceanic-plus)
+
+Make sure to enable `editor.formatOnSave`, so Prettier will automatically apply the right code style. For the full
+immersive experience you can also install and use the [Overpass Mono](https://overpassfont.org/) font.

docs/contributing/testing.md

@@ -0,0 +1,36 @@
+# Testing
+
+Use the following command to test all packages in watch mode. Refer to the [Jest CLI options][jest options] for details.
+
+[jest options]: https://jestjs.io/docs/en/cli#options
+
+```sh
+yarn test:watch
+```
+
+In general, this is sufficient during development. CircleCI and Travis will eventually apply a more rigorous set of
+tests against your pull request, including the ones below.
+
+## Testing the examples
+
+Because React Async is only a piece in a bigger puzzle, testing for integration with other libraries is very important.
+You can run the tests for all examples against your local changes with the following command:
+
+```sh
+yarn test:examples
+```
+
+If you want to add integration tests for compatibility with another library, please add an example for it.
+
+## Testing for compatibility
+
+```sh
+yarn test:compat
+```
+
+This runs all tests using various versions of `react` and `react-dom`, to check for compatibility with older/newer
+versions of React. This is what CircleCI and Travis run.
+
+## Linting
+
+Use `yarn lint` to verify your code style before committing. It's highly recommended to install the Prettier and ESLint plugins for your IDE. CircleCI and Travis will fail your build on lint errors.

examples/basic-fetch/package.json

@@ -14,10 +14,10 @@
     "now-build": "SKIP_PREFLIGHT_CHECK=true react-scripts build"
   },
   "dependencies": {
-    "react": "16.10.2",
+    "react": "16.11.0",
     "react-async": "^9.0.0",
     "react-async-devtools": "^9.0.0",
-    "react-dom": "16.10.2",
+    "react-dom": "16.11.0",
     "react-scripts": "3.2.0"
   },
   "devDependencies": {

examples/basic-hook/package.json

@@ -14,10 +14,10 @@
     "now-build": "SKIP_PREFLIGHT_CHECK=true react-scripts build"
   },
   "dependencies": {
-    "react": "16.10.2",
+    "react": "16.11.0",
     "react-async": "^9.0.0",
     "react-async-devtools": "^9.0.0",
-    "react-dom": "16.10.2",
+    "react-dom": "16.11.0",
     "react-scripts": "3.2.0"
   },
   "devDependencies": {

examples/custom-instance/package.json

@@ -14,10 +14,10 @@
     "now-build": "SKIP_PREFLIGHT_CHECK=true react-scripts build"
   },
   "dependencies": {
-    "react": "16.10.2",
+    "react": "16.11.0",
     "react-async": "^9.0.0",
     "react-async-devtools": "^9.0.0",
-    "react-dom": "16.10.2",
+    "react-dom": "16.11.0",
     "react-scripts": "3.2.0"
   },
   "devDependencies": {