Skip to content

Commit 149ac57

Browse files
phryneasphryneas
committed
Merge remote-tracking branch 'origin/next' into switch-to-ts
2 parents caf3b5d + e8f8099 commit 149ac57

File tree

10 files changed

+286
-21
lines changed

10 files changed

+286
-21
lines changed

‎README.md

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -17,25 +17,12 @@
1717
<img src="https://badgen.net/npm/dm/react-async" alt="montly downloads">
1818
</a>
1919
<a href="https://bundlephobia.com/result?p=react-async">
20-
<img src="https://badgen.net/bundlephobia/min/react-async" alt="minified size">
20+
<img src="https://badgen.net/bundlephobia/minzip/react-async" alt="minzipped size">
2121
</a>
2222
<a href="https://opensource.org/licenses/ISC">
2323
<img src="https://badgen.net/npm/license/react-async" alt="license">
2424
</a>
2525
<br/>
26-
<a href="https://github.com/async-library/react-async/issues">
27-
<img src="https://badgen.net/github/open-issues/async-library/react-async?icon=github" alt="issues">
28-
</a>
29-
<a href="https://github.com/async-library/react-async/pulls">
30-
<img src="https://badgen.net/github/open-prs/async-library/react-async?icon=github" alt="pull requests">
31-
</a>
32-
<a href="https://github.com/async-library/react-async/releases">
33-
<img src="https://badgen.net/github/releases/async-library/react-async?icon=github" alt="releases">
34-
</a>
35-
<a href="https://github.com/async-library/react-async/graphs/contributors">
36-
<img src="https://badgen.net/github/contributors/async-library/react-async?icon=github" alt="contributors">
37-
</a>
38-
<br/>
3926
<a href="https://circleci.com/gh/async-library/react-async">
4027
<img src="https://badgen.net/circleci/github/async-library/react-async/master?icon=circleci" alt="circleci status">
4128
</a>
@@ -52,10 +39,6 @@
5239
<img src="https://deepscan.io/api/teams/5549/projects/7406/branches/74183/badge/grade.svg" alt="DeepScan grade">
5340
</a>
5441
<br/>
55-
<img src="https://badgen.net/david/dep/async-library/react-async/packages/react-async" alt="dependencies">
56-
<img src="https://badgen.net/david/dev/async-library/react-async" alt="devDependencies">
57-
<img src="https://badgen.net/david/peer/async-library/react-async/packages/react-async" alt="peerDependencies">
58-
<br/>
5942
<a href="https://discord.gg/CAYQ6mU">
6043
<img src="https://img.shields.io/badge/discord-join-7289DA.svg?logo=discord&longCache=true&style=flat" />
6144
</a>
@@ -120,6 +103,14 @@ Use it with `fetch`, Axios or other data fetching libraries, even GraphQL.
120103
- [Optimistic updates](https://docs.react-async.com/guide/optimistic-updates)
121104
- [Server-side rendering](https://docs.react-async.com/guide/server-side-rendering)
122105

106+
## Contributing
107+
108+
- [Introduction](https://docs.react-async.com/contributing/introduction)
109+
- [Setting up](https://docs.react-async.com/contributing/setting-up)
110+
- [Development](https://docs.react-async.com/contributing/development)
111+
- [Testing](https://docs.react-async.com/contributing/testing)
112+
- [Releasing](https://docs.react-async.com/contributing/releasing)
113+
123114
# Contributors
124115

125116
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
162153
<!-- ALL-CONTRIBUTORS-LIST:END -->
163154

164155
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
156+
157+
## Similar projects
158+
159+
- [@slorber/react-async-hook](https://github.com/slorber/react-async-hook)
160+
- [@dai-shi/react-hooks-async](https://github.com/dai-shi/react-hooks-async)
161+
- [@cristovao-trevisan/async-resource](https://github.com/cristovao-trevisan/async-resource)
162+
- [@ilyalesik/react-fetch-hook](https://github.com/ilyalesik/react-fetch-hook)
163+
- [@marcin-piela/react-fetching-library](https://github.com/marcin-piela/react-fetching-library)

‎docs/_summary.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,11 @@
2323
- [Async actions](guide/async-actions.md)
2424
- [Optimistic updates](guide/optimistic-updates.md)
2525
- [Server-side rendering](guide/server-side-rendering.md)
26+
27+
## Contributing
28+
29+
- [Introduction](contributing/introduction.md)
30+
- [Setting up](contributing/setting-up.md)
31+
- [Development](contributing/development.md)
32+
- [Testing](contributing/testing.md)
33+
- [Releasing](contributing/releasing.md)

‎docs/contributing/development.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Development
2+
3+
React Async is a library without visual parts. Only the DevTools have a user interface you can spin up in a browser.
4+
Therefore the development workflow for the core library might be different from what you're used to. Generally, we use a
5+
TDD approach:
6+
7+
- Write a unit test for the new feature or bug you want to fix. Sometimes you can just extend an existing test.
8+
- Fix the test by implementing the feature or bugfix. Now all tests should pass.
9+
- Optionally refactor the code for performance, readability and style. Probably this will come up during PR review.
10+
11+
We use the GitHub pull request workflow. In practice this means your workflow looks like this:
12+
13+
- Fork the repo (or pull the latest upstream) under your own account.
14+
- Make your changes, commit and push them. We don't enforce any commit message format.
15+
- Open a pull request on the main repository against the `next` branch. Make sure to follow the template.
16+
- We'll review your PR and will probably ask for some changes.
17+
- Once ready, we'll merge your PR.
18+
- Your changes will be in the next release.
19+
20+
## Working with Storybook
21+
22+
We use Storybook as a development environment for the DevTools. Spin it up using:
23+
24+
```sh
25+
yarn start:storybook
26+
```
27+
28+
This should open up Storybook in a browser at http://localhost:6006/
29+
Run it side-by-side with `yarn test --watch` during development. See [Testing](#testing).
30+
31+
## Working with the examples
32+
33+
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`.
34+
35+
To run sample examples on your local environments
36+
37+
```sh
38+
yarn build:examples
39+
yarn test:examples
40+
yarn start:examples
41+
```
42+
43+
## Resolving issues
44+
45+
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

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Contributing to React Async
2+
3+
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.
4+
5+
This repo relies on Yarn workspaces, so you should [install](https://yarnpkg.com/en/docs/install) and use `yarn@1.3.2` or higher as the package manager for this project.
6+
7+
## Development guide
8+
9+
Please have the **_latest_** stable versions of the following on your machine
10+
11+
- node
12+
- yarn
13+
14+
### Initial setup
15+
16+
To start working on React Async, clone the repo and bootstrap the project:
17+
18+
```sh
19+
git clone https://github.com/async-library/react-async.git
20+
cd react-async
21+
yarn && yarn bootstrap && yarn test
22+
```
23+
24+
Note that all work is done against the `next` branch, we only merge to `master` when doing a release.
25+
26+
### Working with Storybook
27+
28+
We use Storybook as a development environment, particularly for the DevTools. Spin it up using:
29+
30+
```sh
31+
yarn start:storybook
32+
```
33+
34+
This should open up Storybook in a browser at http://localhost:6006/
35+
Run it side-by-side with `yarn test --watch` during development. See [Testing](#testing).
36+
37+
### Linting
38+
39+
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:
40+
41+
```plaintext
42+
"eslint.autoFixOnSave": true,
43+
"eslint.packageManager": "yarn",
44+
"eslint.options": {
45+
"cache": true,
46+
"cacheLocation": ".cache/eslint",
47+
"extensions": [".js", ".jsx", ".mjs", ".json", ".ts", ".tsx"]
48+
},
49+
"eslint.validate": [
50+
"javascript",
51+
"javascriptreact",
52+
{"language": "typescript", "autoFix": true },
53+
{"language": "typescriptreact", "autoFix": true }
54+
],
55+
"eslint.alwaysShowStatus": true
56+
```
57+
58+
This should enable auto-fix for all source files, and give linting warnings and errors within your editor.
59+
60+
### Testing
61+
62+
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.
63+
64+
```sh
65+
yarn test:watch
66+
```
67+
68+
In general, this is sufficient during development. Travis CI will apply a more rigorous set of tests.
69+
70+
#### Testing for compatibility
71+
72+
```sh
73+
yarn test:compat
74+
```
75+
76+
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.
77+
78+
### Working with the examples
79+
80+
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`.
81+
82+
To run sample examples on your local environments
83+
84+
```sh
85+
yarn build:examples
86+
yarn test:examples
87+
yarn start:examples
88+
```
89+
90+
### Resolving issues
91+
92+
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

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

‎docs/contributing/setting-up.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Setting up your development environment
2+
3+
## Prerequisites
4+
5+
In order to develop React Async on your local machine, you'll need `git`, `node` and `yarn`.
6+
7+
### Git
8+
9+
To clone the repository, commit your changes and push them upstream, you'll need to have `git` [installed][install git].
10+
11+
[install git]: https://www.atlassian.com/git/tutorials/install-git
12+
13+
### Node.js
14+
15+
As a JavaScript project, we rely heavily on Node.js. It's recommended to use a version manager such as [fnm] for Mac /
16+
Linux or [nvm-windows] for Windows to install the latest Node.js with.
17+
18+
[fnm]: https://github.com/Schniz/fnm
19+
[nvm-windows]: https://github.com/coreybutler/nvm-windows
20+
21+
### Yarn
22+
23+
This repo relies on Yarn workspaces, so you should [install][install yarn] and use `yarn@1.3.2` or higher as the package
24+
manager for this project.
25+
26+
[install yarn]: https://yarnpkg.com/en/docs/install
27+
28+
## Project setup
29+
30+
To start working on React Async, clone the repository and bootstrap the project by running the following commands
31+
one-by-one:
32+
33+
```sh
34+
git clone https://github.com/async-library/react-async.git
35+
cd react-async
36+
yarn install
37+
yarn bootstrap
38+
yarn test
39+
```
40+
41+
This should install all dependencies, build and link the react-async and react-async-devtools packages to the examples,
42+
and finally run the unit tests. In the end it should succeed with a message (numbers may change):
43+
44+
```
45+
Test Suites: 6 passed, 6 total
46+
Tests: 136 passed, 136 total
47+
```
48+
49+
> Note that all work is done against the `next` branch, we only merge to `master` when doing a release.
50+
51+
## Editor setup
52+
53+
We recommend using [Visual Studio Code](https://code.visualstudio.com/) with the following extensions:
54+
55+
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
56+
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
57+
- [DeepScan](https://marketplace.visualstudio.com/items?itemName=DeepScan.vscode-deepscan)
58+
- [Oceanic Plus](https://marketplace.visualstudio.com/items?itemName=marcoms.oceanic-plus)
59+
60+
Make sure to enable `editor.formatOnSave`, so Prettier will automatically apply the right code style. For the full
61+
immersive experience you can also install and use the [Overpass Mono](https://overpassfont.org/) font.

‎docs/contributing/testing.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Testing
2+
3+
Use the following command to test all packages in watch mode. Refer to the [Jest CLI options][jest options] for details.
4+
5+
[jest options]: https://jestjs.io/docs/en/cli#options
6+
7+
```sh
8+
yarn test:watch
9+
```
10+
11+
In general, this is sufficient during development. CircleCI and Travis will eventually apply a more rigorous set of
12+
tests against your pull request, including the ones below.
13+
14+
## Testing the examples
15+
16+
Because React Async is only a piece in a bigger puzzle, testing for integration with other libraries is very important.
17+
You can run the tests for all examples against your local changes with the following command:
18+
19+
```sh
20+
yarn test:examples
21+
```
22+
23+
If you want to add integration tests for compatibility with another library, please add an example for it.
24+
25+
## Testing for compatibility
26+
27+
```sh
28+
yarn test:compat
29+
```
30+
31+
This runs all tests using various versions of `react` and `react-dom`, to check for compatibility with older/newer
32+
versions of React. This is what CircleCI and Travis run.
33+
34+
## Linting
35+
36+
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.

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@
6666
"eslint-plugin-react": "7.16.0",
6767
"eslint-plugin-react-hooks": "2.1.2",
6868
"jest": "24.9.0",
69-
"lerna": "3.18.1",
69+
"lerna": "3.18.3",
7070
"now": "16.3.1",
7171
"npm-run-all": "4.1.5",
7272
"prettier": "1.18.2",

‎packages/react-async-devtools/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
],
1010
"author": "Gert Hengeveld <info@ghengeveld.nl>",
1111
"license": "ISC",
12-
"homepage": "https://async-library.com",
12+
"homepage": "https://react-async.com/",
1313
"repository": {
1414
"type": "git",
1515
"url": "https://github.com/async-library/react-async.git",

‎packages/react-async/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
],
1212
"author": "Gert Hengeveld <info@ghengeveld.nl>",
1313
"license": "ISC",
14-
"homepage": "https://async-library.com",
14+
"homepage": "https://react-async.com/",
1515
"repository": {
1616
"type": "git",
1717
"url": "https://github.com/async-library/react-async.git",

0 commit comments

Comments
 (0)