Merge branch 'vuex-docs-fix' into 'master'

Changed actions pattern in Vuex guideline

See merge request gitlab-org/gitlab!31302

doc/development/fe_guide/vue.md

@@ -321,7 +321,7 @@ One should apply to be a Vue.js expert by opening an MR when the Merge Request's
 - Deep understanding of Vue and Vuex reactivity
 - Vue and Vuex code are structured according to both official and our guidelines
 - Full understanding of testing a Vue and Vuex application
-- Vuex code follows the [documented pattern](vuex.md#actions-pattern-request-and-receive-namespaces)
+- Vuex code follows the [documented pattern](vuex.md#naming-pattern-request-and-receive-namespaces)
 - Knowledge about the existing Vue and Vuex applications and existing reusable components
 
 ## Vue 2 -> Vue 3 Migration

doc/development/fe_guide/vuex.md

@@ -86,71 +86,35 @@ You can use `mapState` to access state properties in the components.
 
 An action is a payload of information to send data from our application to our store.
 
-An action is usually composed by a `type` and a `payload` and they describe what happened.
-Enforcing that every change is described as an action lets us have a clear understanding of what is going on in the app.
+An action is usually composed by a `type` and a `payload` and they describe what happened. Unlike [mutations](#mutationsjs), actions can contain asynchronous operations - that's why we always need to handle asynchronous logic in actions.
 
-In this file, we will write the actions that will call the respective mutations:
+In this file, we will write the actions that will call mutations for handling a list of users:
 
 ```javascript
   import * as types from './mutation_types';
   import axios from '~/lib/utils/axios_utils';
   import createFlash from '~/flash';
 
-  export const requestUsers = ({ commit }) => commit(types.REQUEST_USERS);
-  export const receiveUsersSuccess = ({ commit }, data) => commit(types.RECEIVE_USERS_SUCCESS, data);
-  export const receiveUsersError = ({ commit }, error) => commit(types.RECEIVE_USERS_ERROR, error);
-
   export const fetchUsers = ({ state, dispatch }) => {
-    dispatch('requestUsers');
+    commit(types.REQUEST_USERS);
 
     axios.get(state.endpoint)
-      .then(({ data }) => dispatch('receiveUsersSuccess', data))
+      .then(({ data }) => commit(types.RECEIVE_USERS_SUCCESS, data))
       .catch((error) => {
-        dispatch('receiveUsersError', error)
+        commit(types.RECEIVE_USERS_ERROR, error)
         createFlash('There was an error')
       });
   }
 
-  export const requestAddUser = ({ commit }) => commit(types.REQUEST_ADD_USER);
-  export const receiveAddUserSuccess = ({ commit }, data) => commit(types.RECEIVE_ADD_USER_SUCCESS, data);
-  export const receiveAddUserError = ({ commit }, error) => commit(types.REQUEST_ADD_USER_ERROR, error);
-
   export const addUser = ({ state, dispatch }, user) => {
-    dispatch('requestAddUser');
+    commit(types.REQUEST_ADD_USER);
 
     axios.post(state.endpoint, user)
-      .then(({ data }) => dispatch('receiveAddUserSuccess', data))
-      .catch((error) => dispatch('receiveAddUserError', error));
+      .then(({ data }) => commit(types.RECEIVE_ADD_USER_SUCCESS, data))
+      .catch((error) => commit(types.REQUEST_ADD_USER_ERROR, error));
   }
 ```
 
-#### Actions Pattern: `request` and `receive` namespaces
-
-When a request is made we often want to show a loading state to the user.
-
-Instead of creating an action to toggle the loading state and dispatch it in the component,
-create:
-
-1. An action `requestSomething`, to toggle the loading state
-1. An action `receiveSomethingSuccess`, to handle the success callback
-1. An action `receiveSomethingError`, to handle the error callback
-1. An action `fetchSomething` to make the request.
-    1. In case your application does more than a `GET` request you can use these as examples:
-        - `POST`: `createSomething`
-        - `PUT`: `updateSomething`
-        - `DELETE`: `deleteSomething`
-
-The component MUST only dispatch the `fetchNamespace` action. Actions namespaced with `request` or `receive` should not be called from the component
-The `fetch` action will be responsible to dispatch `requestNamespace`, `receiveNamespaceSuccess` and `receiveNamespaceError`
-
-By following this pattern we guarantee:
-
-1. All applications follow the same pattern, making it easier for anyone to maintain the code
-1. All data in the application follows the same lifecycle pattern
-1. Actions are contained and human friendly
-1. Unit tests are easier
-1. Actions are simple and straightforward
-
 #### Dispatching actions
 
 To dispatch an action from a component, use the `mapActions` helper:
@@ -181,6 +145,8 @@ Remember that actions only describe that something happened, they don't describe
 
 **Never commit a mutation directly from a component**
 
+Instead, you should create an action that will commit a mutation.
+
 ```javascript
   import * as types from './mutation_types';
 
@@ -210,6 +176,31 @@ Remember that actions only describe that something happened, they don't describe
   };
 ```
 
+#### Naming Pattern: `REQUEST` and `RECEIVE` namespaces
+
+When a request is made we often want to show a loading state to the user.
+
+Instead of creating an mutation to toggle the loading state, we should:
+
+1. A mutation with type `REQUEST_SOMETHING`, to toggle the loading state
+1. A mutation with type `RECEIVE_SOMETHING_SUCCESS`, to handle the success callback
+1. A mutation with type `RECEIVE_SOMETHING_ERROR`, to handle the error callback
+1. An action `fetchSomething` to make the request and commit mutations on mentioned cases
+    1. In case your application does more than a `GET` request you can use these as examples:
+        - `POST`: `createSomething`
+        - `PUT`: `updateSomething`
+        - `DELETE`: `deleteSomething`
+
+As a result, we can dispatch the `fetchNamespace` action from the component and it will be responsible to commit  `REQUEST_NAMESPACE`, `RECEIVE_NAMESPACE_SUCCESS` and `RECEIVE_NAMESPACE_ERROR` mutations.
+
+> Previously, we were dispatching actions from the `fetchNamespace` action instead of committing mutation, so please don't be confused if you find a different pattern in the older parts of the codebase. However, we encourage leveraging a new pattern whenever you write new Vuex stores
+
+By following this pattern we guarantee:
+
+1. All applications follow the same pattern, making it easier for anyone to maintain the code
+1. All data in the application follows the same lifecycle pattern
+1. Unit tests are easier
+
 ### `getters.js`
 
 Sometimes we may need to get derived state based on store state, like filtering for a specific prop.