Merge branch 'master' into use-tracked-state

Author: dai-shi

.github/ISSUE_TEMPLATE/---bug-report.md

@@ -0,0 +1,33 @@
+---
+name: "\U0001F41B Bug report"
+about: Something isn't working correctly.
+
+---
+<!--
+Thank you for contributing to open source!
+
+Do you need some help?
+======================
+
+The issue tracker is meant for bug reports only. This isn't the best place for support or usage questions. Questions here don't have as much visibility as they do elsewhere. Before you ask a question, here are some resources to get help first:
+
+- Read the docs: https://react-redux.js.org/
+- Check out the troubleshooting guide: https://react-redux.js.org/troubleshooting
+- Look for/ask questions on Stack Overflow: https://stackoverflow.com/questions/tagged/redux
+- Ask in chat: https://www.reactiflux.com/
+
+Think you found a bug?
+======================
+The best bug report is a failing test in the repository as a pull request. Otherwise, please use the template below.
+
+-->
+
+**What is the current behavior?**
+
+If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem. Your bug will get fixed much faster if we can run your code and it doesn't have dependencies other than React. Paste the link to a CodeSandbox (https://codesandbox.io/s/new) or RN Snack (https://snack.expo.io/) example below:
+
+
+
+**What is the expected behavior?**
+
+Which versions of React, ReactDOM/React Native, Redux, and React Redux are you using?  Which browser and OS are affected by this issue? Did this work in previous versions of React Redux?

.github/ISSUE_TEMPLATE/---support-usage-question.md

@@ -0,0 +1,36 @@
+---
+name: 👍 Feature Request
+about: I'd like React Redux to do something new.
+---
+
+<!--
+Thank you for contributing to open source!
+
+Do you need some help?
+======================
+
+The issue tracker is meant for feature requests and bug reports only. This isn't the best place for 
+support or usage questions. Questions here don't have as much visibility as they do elsewhere. Before 
+you ask a question, here are some resources to get help first:
+
+- Read the docs: https://react-redux.js.org/
+- Check out the troubleshooting guide: https://react-redux.js.org/troubleshooting
+- Look for/ask questions on Stack Overflow: https://stackoverflow.com/questions/tagged/redux
+- Ask in chat: https://www.reactiflux.com/
+
+Have a feature request?
+=======================
+Remove the template from below and provide thoughtful commentary *and code samples* on what this 
+feature means for your product. What will it allow you to do that you can't do today? How will it 
+make current work-arounds straightforward? What potential bugs and edge cases does it help to 
+avoid? etc. Please keep it product-centric.
+
+-->
+
+## New Features
+
+### What is the new or updated feature that you are suggesting?
+
+### Why should this feature be included?
+
+### What docs changes are needed to explain this?

.github/ISSUE_TEMPLATE/Bug_report.md

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+    - name: 🤔 Questions and Help
+      url: https://redux.js.org/introduction/getting-started#help-and-discussion
+      about: This is a bug tracker, not a support system. For usage questions, please use our support resources.

.github/ISSUE_TEMPLATE/Feature_request.md

@@ -0,0 +1,15 @@
+name: Compressed Size
+
+on: [pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2-beta
+        with:
+          fetch-depth: 1
+      - uses: preactjs/compressed-size-action@v1
+        with:
+          repo-token: '${{ secrets.GITHUB_TOKEN }}'

.github/ISSUE_TEMPLATE/config.yml

@@ -11,12 +11,30 @@ Performant and flexible.
 
 ## Installation
 
-React Redux requires **React 16.8.3 or later.**
+### Using Create React App
 
+The recommended way to start new apps with React Redux is by using the [official Redux+JS template](https://github.com/reduxjs/cra-template-redux) for [Create React App](https://github.com/facebook/create-react-app), which takes advantage of [Redux Toolkit](https://redux-toolkit.js.org/).
+
+```sh
+npx create-react-app my-app --template redux
 ```
-npm install --save react-redux
+
+### An Existing React App
+
+React Redux 7.1 requires **React 16.8.3 or later.**
+
+To use React Redux with your React app, install it as a dependency:
+
+```bash
+# If you use npm:
+npm install react-redux
+
+# Or if you use Yarn:
+yarn add react-redux
 ```
 
+You'll also need to [install Redux](https://redux.js.org/introduction/installation) and [set up a Redux store](https://redux.js.org/recipes/configuring-your-store/) in your app.
+
 This assumes that you’re using [npm](http://npmjs.com/) package manager 
 with a module bundler like [Webpack](https://webpack.js.org/) or 
 [Browserify](http://browserify.org/) to consume [CommonJS 

.github/workflows/main.yaml

@@ -124,9 +124,9 @@ The second parameter is normally referred to as `ownProps` by convention.
 <button onClick={() => this.props.toggleTodo(this.props.todoId)} />
 
 // binds on `props` change
-const mapDispatchToProps = (dispatch, ownProps) => {
+const mapDispatchToProps = (dispatch, ownProps) => ({
   toggleTodo: () => dispatch(toggleTodo(ownProps.todoId))
-}
+})
 ```
 
 The number of declared function parameters of `mapDispatchToProps` determines whether they receive ownProps. See notes [here](#the-arity-of-maptoprops-functions).

README.md

@@ -33,14 +33,14 @@ From there, you may import any of the listed React Redux hooks APIs and use them
 ## `useSelector()`
 
 ```js
-const result : any = useSelector(selector : Function, equalityFn? : Function)
+const result: any = useSelector(selector: Function, equalityFn?: Function)
 ```
 
 Allows you to extract data from the Redux store state, using a selector function.
 
 > **Note**: The selector function should be [pure](https://en.wikipedia.org/wiki/Pure_function) since it is potentially executed multiple times and at arbitrary points in time.
 
-The selector is approximately equivalent to the [`mapStateToProps` argument to `connect`](../using-react-redux/connect-extracting-data-with-mapStateToProps.md) conceptually. The selector will be called with the entire Redux store state as its only argument. The selector will be run whenever the function component renders. `useSelector()` will also subscribe to the Redux store, and run your selector whenever an action is dispatched.
+The selector is approximately equivalent to the [`mapStateToProps` argument to `connect`](../using-react-redux/connect-mapstate) conceptually. The selector will be called with the entire Redux store state as its only argument. The selector will be run whenever the function component renders (unless its reference hasn't changed since a previous render of the component so that a cached result can be returned by the hook without re-running the selector). `useSelector()` will also subscribe to the Redux store, and run your selector whenever an action is dispatched.
 
 However, there are some differences between the selectors passed to `useSelector()` and a `mapState` function:
 
@@ -57,7 +57,7 @@ You may call `useSelector()` multiple times within a single function component.
 ### Equality Comparisons and Updates
 
 When the function component renders, the provided selector function will be called and its result will be returned
-from the `useSelector()` hook. (A cached result may be returned if the selector has been run and hasn't changed.)
+from the `useSelector()` hook. (A cached result may be returned by the hook without re-running the selector if it's the same function reference as on a previous render of the component.)
 
 However, when an action is dispatched to the Redux store, `useSelector()` only forces a re-render if the selector result
 appears to be different than the last result. As of v7.1.0-alpha.5, the default comparison is a strict `===` reference

docs/api/connect.md

@@ -277,7 +277,7 @@ const TodoList = // ... UI component implementation
 export default connect(state => ({ todos: getTodos(state) }))(TodoList);
 ```
 
-We recommend encapsulating any complex lookups or computations of data in selector functions. In addition, you can further optimize the performance by using [Reselect](https://github.com/reduxjs/reselect) to write “memoized” selectors that can skip unnecessary work. (See [the Redux docs page on Computing Derived Data](https://redux.js.org/recipes/computingderiveddata#sharing-selectors-across-multiple-components) and the blog post [Idiomatic Redux: Using Reselect Selectors for Encapsulation and Performance](https://blog.isquaredsoftware.com/2017/12/idiomatic-redux-using-reselect-selectors/) for more information on why and how to use selector functions.)
+We recommend encapsulating any complex lookups or computations of data in selector functions. In addition, you can further optimize the performance by using [Reselect](https://github.com/reduxjs/reselect) to write “memoized” selectors that can skip unnecessary work. (See [the Redux docs page on Computing Derived Data](https://redux.js.org/recipes/computing-derived-data#sharing-selectors-across-multiple-components) and the blog post [Idiomatic Redux: Using Reselect Selectors for Encapsulation and Performance](https://blog.isquaredsoftware.com/2017/12/idiomatic-redux-using-reselect-selectors/) for more information on why and how to use selector functions.)
 
 Now that our `<TodoList />` is connected to the store. It should receive the list of todos, map over them, and pass each todo to the `<Todo />` component. `<Todo />` will in turn render them to the screen. Now try adding a todo. It should come up on our todo list!
 

docs/api/hooks.md

@@ -13,19 +13,27 @@ sidebar_label: Quick Start
 
 React Redux 7.1 requires **React 16.8.3 or later.**
 
-To use React Redux with your React app:
+### Using Create React App
 
-```bash
-npm install react-redux
+The recommended way to start new apps with React Redux is by using the [official Redux+JS template](https://github.com/reduxjs/cra-template-redux) for [Create React App](https://github.com/facebook/create-react-app), which takes advantage of [Redux Toolkit](https://redux-toolkit.js.org/).
+
+```sh
+npx create-react-app my-app --template redux
 ```
 
-or
+### An Existing React App
+
+To use React Redux with your React app, install it as a dependency:
 
 ```bash
+# If you use npm:
+npm install react-redux
+
+# Or if you use Yarn:
 yarn add react-redux
 ```
 
-You'll also need to [install Redux](https://redux-docs.netlify.com/introduction/installation) and [set up a Redux store](https://redux-docs.netlify.com/recipes/configuring-your-store) in your app.
+You'll also need to [install Redux](https://redux.js.org/introduction/installation) and [set up a Redux store](https://redux.js.org/recipes/configuring-your-store/) in your app.
 
 ## `Provider`
 

docs/introduction/basic-tutorial.md

@@ -26,6 +26,10 @@ by a single default context object instance generated by `React.createContext()`
 React Redux's `<Provider>` component uses `<ReactReduxContext.Provider>` to put the Redux store and the current store
 state into context, and `connect` uses `<ReactReduxContext.Consumer>` to read those values and handle updates.
 
+## Using the `useStore` Hook
+
+The [`useStore` hook](../api/hooks.md#useStore) returns the current store instance from the default `ReactReduxContext`. If you truly need to access the store, this is the recommended approach.
+
 ## Providing Custom Context
 
 Instead of using the default context instance from React Redux, you may supply your own custom context instance.

docs/introduction/quick-start.md

@@ -159,7 +159,9 @@ render() {
 }
 
 const mapDispatchToProps = dispatch => {
-  toggleTodo: todoId => dispatch(toggleTodo(todoId))
+  return {
+    toggleTodo: todoId => dispatch(toggleTodo(todoId))
+  }
 }
 ```
 
@@ -171,7 +173,9 @@ render() {
 }
 
 const mapDispatchToProps = (dispatch, ownProps) => {
-  toggleTodo: () => dispatch(toggleTodo(ownProps.todoId))
+  return {
+    toggleTodo: () => dispatch(toggleTodo(ownProps.todoId))
+  }
 }
 ```