Add latest changes from gitlab-org/gitlab@master

app/assets/javascripts/work_items/components/work_item_links/work_item_children_wrapper.vue

@@ -8,8 +8,8 @@ import { DEFAULT_DEBOUNCE_AND_THROTTLE_MS } from '~/lib/utils/constants';
 import { s__ } from '~/locale';
 import { defaultSortableOptions, DRAG_DELAY } from '~/sortable/constants';
 
-import { WORK_ITEM_TYPE_VALUE_OBJECTIVE, DEFAULT_PAGE_SIZE_CHILD_ITEMS } from '../../constants';
-import { findHierarchyWidgets } from '../../utils';
+import { WORK_ITEM_TYPE_VALUE_OBJECTIVE } from '../../constants';
+import { findHierarchyWidgets, getDefaultHierarchyChildrenCount } from '../../utils';
 import { addHierarchyChild, removeHierarchyChild } from '../../graphql/cache_utils';
 import reorderWorkItem from '../../graphql/reorder_work_item.mutation.graphql';
 import updateWorkItemMutation from '../../graphql/update_work_item.mutation.graphql';
@@ -237,7 +237,7 @@ export default {
             store.updateQuery(
               {
                 query: getWorkItemTreeQuery,
-                variables: { id: this.workItemId, pageSize: DEFAULT_PAGE_SIZE_CHILD_ITEMS },
+                variables: { id: this.workItemId, pageSize: getDefaultHierarchyChildrenCount() },
               },
               (sourceData) =>
                 produce(sourceData, (draftData) => {

app/assets/javascripts/work_items/components/work_item_links/work_item_link_child.vue

@@ -11,9 +11,8 @@ import {
   WIDGET_TYPE_HIERARCHY,
   WORK_ITEM_TYPE_VALUE_OBJECTIVE,
   WORK_ITEM_TYPE_VALUE_TASK,
-  DEFAULT_PAGE_SIZE_CHILD_ITEMS,
 } from '../../constants';
-import { findHierarchyWidgets } from '../../utils';
+import { findHierarchyWidgets, getDefaultHierarchyChildrenCount } from '../../utils';
 import getWorkItemTreeQuery from '../../graphql/work_item_tree.query.graphql';
 import WorkItemLinkChildContents from '../shared/work_item_link_child_contents.vue';
 import WorkItemChildrenLoadMore from '../shared/work_item_children_load_more.vue';
@@ -88,7 +87,7 @@ export default {
       variables() {
         return {
           id: this.childItemId,
-          pageSize: DEFAULT_PAGE_SIZE_CHILD_ITEMS,
+          pageSize: getDefaultHierarchyChildrenCount(),
           endCursor: '',
         };
       },

app/assets/javascripts/work_items/components/work_item_links/work_item_tree.vue

@@ -12,9 +12,8 @@ import {
   WORK_ITEM_TYPE_ENUM_KEY_RESULT,
   WORK_ITEM_TYPE_ENUM_EPIC,
   CHILD_ITEMS_ANCHOR,
-  DEFAULT_PAGE_SIZE_CHILD_ITEMS,
 } from '../../constants';
-import { findHierarchyWidgets } from '../../utils';
+import { findHierarchyWidgets, getDefaultHierarchyChildrenCount } from '../../utils';
 import getWorkItemTreeQuery from '../../graphql/work_item_tree.query.graphql';
 import WorkItemChildrenLoadMore from '../shared/work_item_children_load_more.vue';
 import WidgetWrapper from '../widget_wrapper.vue';
@@ -113,7 +112,7 @@ export default {
       variables() {
         return {
           id: this.workItemId,
-          pageSize: DEFAULT_PAGE_SIZE_CHILD_ITEMS,
+          pageSize: getDefaultHierarchyChildrenCount(),
           endCursor: '',
         };
       },

app/assets/javascripts/work_items/utils.js

@@ -1,4 +1,5 @@
 import { getIdFromGraphQLId } from '~/graphql_shared/utils';
+import { queryToObject } from '~/lib/utils/url_utility';
 import {
   NEW_WORK_ITEM_IID,
   WIDGET_TYPE_ASSIGNEES,
@@ -22,6 +23,7 @@ import {
   WORK_ITEM_TYPE_ENUM_KEY_RESULT,
   WORK_ITEM_TYPE_ENUM_REQUIREMENTS,
   NEW_WORK_ITEM_GID,
+  DEFAULT_PAGE_SIZE_CHILD_ITEMS,
 } from './constants';
 
 export const isAssigneesWidget = (widget) => widget.type === WIDGET_TYPE_ASSIGNEES;
@@ -58,6 +60,18 @@ export const getWorkItemIcon = (icon) => {
   return icon;
 };
 
+/**
+ * TODO: Remove this method with https://gitlab.com/gitlab-org/gitlab/-/issues/479637
+ * We're currently setting children count per page based on `DEFAULT_PAGE_SIZE_CHILD_ITEMS`
+ * but we need to find an ideal page size that's usable and fast enough. In order to test
+ * correct page size in production with actual data, this method allows us to set page
+ * size using query param (while falling back to `DEFAULT_PAGE_SIZE_CHILD_ITEMS`).
+ */
+export const getDefaultHierarchyChildrenCount = () => {
+  const { children_count } = queryToObject(window.location.search);
+  return Number(children_count) || DEFAULT_PAGE_SIZE_CHILD_ITEMS;
+};
+
 export const formatAncestors = (workItem) =>
   findHierarchyWidgetAncestors(workItem).map((ancestor) => ({
     ...ancestor,

doc/.vale/gitlab_base/spelling-exceptions.txt

@@ -388,8 +388,8 @@ Gbps
 Gemfile
 Gemnasium
 Gemojione
-Getter
-Getters
+getter
+getters
 gettext
 GIDs
 gists
@@ -698,6 +698,7 @@ phpenv
 Phorge
 PHPUnit
 PIDs
+Pinia
 pipenv
 Pipfile
 Pipfiles

doc/ci/environments/index.md

@@ -699,6 +699,28 @@ To delete an environment:
 1. Next to the environment you want to delete, select **Delete environment**.
 1. On the confirmation dialog, select **Delete environment**.
 
+### Clean up stale environments
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108616) in GitLab 15.8 [with a flag](../../administration/feature_flags.md) named `stop_stale_environments`. Disabled by default.
+> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112098) in GitLab 15.10. Feature flag `stop_stale_environments` removed.
+
+Clean up stale environments when you want to stop old environments in a project.
+
+Prerequisites:
+
+- You must have at least the Maintainer role.
+
+To clean up stale environments:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Operate > Environments**.
+1. Select **Clean up environments**.
+1. Select the date to use for determining which environments to consider stale.
+1. Select **Clean up**.
+
+Active environments that haven't been updated after the specified date are stopped.
+Protected environments are ignored and not stopped.
+
 ### Access an environment for preparation or verification purposes
 
 You can define a job that accesses an environment for various purposes, such as verification or preparation. This

doc/development/fe_guide/graphql.md

@@ -413,13 +413,16 @@ For each attempt to fetch a version, our client fetches `id` and `sha` from the
 
 Read more about local state management with Apollo in the [Vue Apollo documentation](https://vue-apollo.netlify.app/guide/local-state.html#local-state).
 
+### Using with Pinia
+
+Combining [Pinia](pinia.md) and Apollo in a single Vue application is generally discouraged.
+[Learn about the restrictions and circumstances around combining Apollo and Pinia](state_management.md#combining-pinia-and-apollo).
+
 ### Using with Vuex
 
-We do not recommend creating new applications with Vuex and Apollo Client combined. There are a few reasons:
-
-- VueX and Apollo are both **global stores**, which means sharing responsibilities and having two sources of truth.
-- Keeping VueX and Apollo in sync can be high maintenance.
-- Bugs that would come from the communication between Apollo and VueX would be subtle and hard to debug.
+We do not recommend combining Vuex and Apollo Client. [Vuex is deprecated in GitLab](vuex.md#deprecated).
+If you have an existing Vuex store that's used alongside Apollo we strongly recommend [migrating away from Vuex entirely](migrating_from_vuex.md).
+[Learn more about state management in GitLab](state_management.md).
 
 ### Working on GraphQL-based features when frontend and backend are not in sync
 

doc/development/fe_guide/index.md

@@ -24,12 +24,19 @@ When it comes to CSS, we use a utils-based CSS approach. GitLab has its own CSS
 We also use [SCSS](https://sass-lang.com) and plain JavaScript with
 modern ECMAScript standards supported through [Babel](https://babeljs.io/) and ES module support through [webpack](https://webpack.js.org/).
 
-When making API calls, we use [GraphQL](graphql.md) as [the first choice](../api_graphql_styleguide.md#vision). There are still instances where GitLab REST API is used such as when creating new simple HAML pages or in legacy part of the codebase, but we should always default to GraphQL when possible.
+When making API calls, we use [GraphQL](graphql.md) as [the first choice](../api_graphql_styleguide.md#vision).
+There are still instances where the GitLab REST API is used, such as when creating new simple HAML pages, or in legacy parts of the codebase, but we should always default to GraphQL when possible.
 
-We use [Apollo](https://www.apollographql.com/) as our global state manager and [GraphQL client](graphql.md).
-[VueX](vuex.md) is still in use across the codebase, but it is no longer the recommended global state manager.
-You should **not** [use VueX and Apollo together](graphql.md#using-with-vuex),
-and should [avoid adding new VueX stores](migrating_from_vuex.md) whenever possible.
+For [client-side state management](state_management.md) in Vue, depending on the specific needs of the feature,
+we use:
+
+- [Apollo](https://www.apollographql.com/) (our primary [GraphQL client](graphql.md))
+- [Pinia](pinia.md) (in [pilot phase](https://gitlab.com/gitlab-org/gitlab/-/issues/479279))
+- Stateful components.
+
+[Vuex is deprecated](vuex.md) and you should [migrate away from it](migrating_from_vuex.md) whenever possible.
+
+Learn: [How do I know which state manager to use?](state_management.md)
 
 For copy strings and translations, we have frontend utilities available. See the JavaScript section of [Preparing a page for translation](../i18n/externalization.md#javascript-files) for more information.
 

doc/development/fe_guide/migrating_from_vuex.md

@@ -6,6 +6,8 @@ info: Any user with at least the Maintainer role can merge updates to this conte
 
 # Migrating from Vuex
 
+[Vuex is deprecated in GitLab](vuex.md#deprecated), if you have an existing Vuex store you should strongly consider migrating.
+
 ## Why?
 
 We have defined the [GraphQL API](../../api/graphql/index.md) as [the primary API](../api_graphql_styleguide.md#vision) for all user-facing features,
@@ -18,7 +20,12 @@ pure Vue and Apollo, or how to rely less on VueX.
 
 ## How?
 
-### Overview
+[Pick your preferred state manager solution](state_management.md) before proceeding with the migration.
+
+- If you plan to use Pinia (in pilot phase), [follow this guide](pinia.md#migrating-from-vuex).
+- If you plan to use Apollo Client for all state management, then [follow the guide below](#migrate-to-vue-managed-state-and-apollo-client).
+
+### Migrate to Vue-managed state and Apollo Client
 
 As a whole, we want to understand how complex our change will be. Sometimes, we only have a few properties that are truly worth being stored in a global state and sometimes they can safely all be extracted to pure `Vue`. `VueX` properties generally fall into one of these categories:
 
@@ -302,17 +309,3 @@ Now that we have gone through each type of data, let's review how to plan for th
 1. Replace network data with Apollo Client, either with actual GraphQL calls when available or by using client-side resolvers to make REST calls.
 
 If it is impossible to quickly replace shared read/write operations or network data (for example in one or two milestones), consider making a different Vue component behind a feature flag that is exclusively functional with Apollo Client, and rename the current component that uses VueX with a `legacy-` prefix. The newer component might not be able to implement all functionality right away, but we can progressively add them as we make MRs. This way, our legacy component is exclusively using VueX as a store and the new one is only Apollo. After the new component has re-implemented all the logic, we can turn the Feature Flag on and ensure that it behaves as expected.
-
-## FAQ
-
-### What if I need a global store without any network call?
-
-This is a rare occurrence and should suggest the following question: "Do I **really** need a global store then?" (the answer is probably no!) If the answer is yes, then you can use the [shared read/write technique with Apollo](#how-to-migrate-reactive-mutable-values) described above. It is perfectly acceptable to use Apollo Client for client-side exclusive stores.
-
-### Are we going to use Pinia?
-
-The short answer is: we don't know, but it is unlikely. It would still mean having two global store libraries, which has the same downsides as VueX and Apollo Client coexisting. Reducing the size of our global stores is positive regardless of whether we end up using Pinia though!
-
-### Apollo client is really verbose for client directives. Can I mix and match with VueX?
-
-Mixing and matching is not recommended. There are a lot of reasons why, but think of how codebases grow organically with what is available. Even if you were really good at separating your network state and your client-side state, other developers might not share the same dedication or simply not understand how to choose what lives in which store. Over time, you will also nearly inevitably need to communicate between your VueX store and Apollo Client, which can only result in problems.

doc/development/fe_guide/pinia.md

@@ -0,0 +1,94 @@
+---
+stage: none
+group: unassigned
+info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
+---
+
+# Pinia
+
+WARNING:
+**[Pilot Phase](https://gitlab.com/gitlab-org/gitlab/-/issues/479279)**: Adopt Pinia with caution.
+This is a new technology at GitLab and we might not have all the necessary precautions and best practices in place yet.
+If you're considering using Pinia please drop a message in the `#frontend` internal Slack channel for evaluation.
+
+[Pinia](https://pinia.vuejs.org/) is a tool for [managing client-side state](state_management.md) for Vue applications.
+Refer to the [official documentation](https://pinia.vuejs.org/core-concepts/) on how to use Pinia.
+
+## Best practices
+
+### Small stores
+
+Prefer creating small stores that focus on a single task only.
+This is contrary to the Vuex approach which encourages you to create bigger stores.
+
+Treat Pinia stores like cohesive components rather than giant state façades (Vuex modules).
+
+### Single file stores
+
+Place state, actions, and getters in a single file.
+Do not create 'barrel' store index files which import everything from `actions.js`, `state.js` and `getters.js`.
+
+If your store file gets too big it's time to consider splitting that store into multiple stores.
+
+### Use Option Stores
+
+Pinia offers two types of store definitions: [option](https://pinia.vuejs.org/core-concepts/#Option-Stores) and [setup](https://pinia.vuejs.org/core-concepts/#Setup-Stores).
+Prefer the option type when creating new stores. This promotes consistency and will simplify the migration path from Vuex.
+
+### Before Pinia
+
+```mermaid
+flowchart TD
+    A[Store]
+    A --> B[State]
+    A --> C[Actions]
+    A --> D[Mutations]
+    A --> E[Getters]
+    B --> F[items]
+    B --> G[isLoadingItems]
+    B --> H[itemWithActiveForm]
+    B --> I[isSubmittingForm]
+```
+
+### After Pinia
+
+```mermaid
+flowchart TD
+    A[Items Store]
+    A --> B[State]
+    A --> C[Actions]
+    A --> D[Getters]
+    B --> E[items]
+    B --> F[isLoading]
+
+    H[Form Store]
+    H --> I[State]
+    H --> J[Actions]
+    H --> K[Getters]
+    I --> L[activeItem]
+    I --> M[isSubmitting]
+```
+
+## Migrating from Vuex
+
+Decide what your primary [state manager](state_management.md) should be first.
+Proceed with this guide if Pinia was your choice.
+
+[Follow the official Vuex migration guide](https://pinia.vuejs.org/cookbook/migration-vuex.html).
+
+Try to split all your migrations into two steps:
+
+1. Refactor just the Vuex API: Don't change the store structure, make sure it works in Pinia ([example](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/149489)).
+1. Refactor the structure: Split your store into multiple smaller, single purpose stores.
+
+### Migrating stores with nested modules
+
+It is not trivial to iteratively migrate stores with nested modules that have dependencies between them.
+In such cases prefer migrating nested modules first:
+
+1. Create a Pinia store counterpart of the nested Vuex store module.
+1. Create a placeholder Pinia 'root' store for root module dependencies if applicable.
+1. Copy and adapt existing tests for the migrated module.
+1. **Do not use migrated modules yet.**
+1. Once all the nested modules are migrated you can migrate the root module and replace the placeholder store with the real one.
+1. Replace Vuex store with Pinia stores in components.

doc/development/fe_guide/state_management.md

@@ -0,0 +1,138 @@
+---
+stage: none
+group: unassigned
+info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
+---
+
+# State management guidance
+
+At GitLab we support two solutions for client state management: [Apollo](https://www.apollographql.com/) and [Pinia](https://pinia.vuejs.org/).
+It is non-trivial to pick either of these as your primary state manager.
+This page should provide you with general guidance on how to make this choice.
+
+You may also see Vuex in the GitLab codebase. [Vuex is deprecated in GitLab](vuex.md#deprecated) and **no new Vuex stores should be created**.
+If your app has a Vuex store, [consider migrating](migrating_from_vuex.md).
+
+## Difference between state and data
+
+**Data** is information that user interacts with.
+It usually comes from external requests (GraphQL or REST) or from the page itself.
+
+**State** stores information about user or system interactions.
+For example any flag is considered state: `isLoading`, `isFormVisible`, etc.
+
+State management could be used to work with both state and data.
+
+## Do I need to have state management?
+
+You should prefer using the standard Vue data flow in your application first:
+components define local state and pass it down through props and change it through events.
+
+However this might not be sufficient for complex cases where state is shared between multiple components
+that are not direct descendants of the component which defined this state.
+You might consider hoisting that state to the root of your application, but that eventually
+bloats the root component because it starts to do too many things at once.
+
+To deal with that complexity you can use a state management solution.
+The sections below will help you with this choice.
+If you're still uncertain, prefer using Apollo before Pinia.
+
+## Apollo
+
+[Apollo](https://www.apollographql.com/), our primary interface to GraphQL API, can also be used as a client-side state manager.
+[Learn more about GraphQL and Apollo](graphql.md).
+
+### Strengths
+
+- Great for working with data from GraphQL requests,
+  provides [data normalization](https://www.apollographql.com/docs/react/caching/overview#data-normalization) out of the box.
+- Can cache data from REST API when GraphQL is not available.
+- Queries are statically verified against the GraphQL schema.
+
+### Weaknesses
+
+- [More complex and involved than Pinia for client state management](https://www.apollographql.com/docs/react/local-state/managing-state-with-field-policies).
+- Apollo DevTools: don't properly work on a significant part of our pages, Apollo Client errors are hard to track down.
+
+### Pick Apollo when
+
+- You rely on the GraphQL server state
+- You need specific Apollo features, for example:
+  - [Parametrized cache, cache invalidation](graphql.md#immutability-and-cache-updates)
+  - [Polling](graphql.md#polling-and-performance)
+  - [Stale While Revalidate](https://www.apollographql.com/docs/react/caching/advanced-topics#persisting-the-cache)
+  - [Real-time updates](graphql.md#subscriptions)
+  - [Other](https://www.apollographql.com/docs/react/)
+
+## Pinia
+
+WARNING:
+**[Pilot Phase](https://gitlab.com/gitlab-org/gitlab/-/issues/479279)**: Adopt Pinia with caution.
+This is a new technology at GitLab and we might not have all the necessary precautions and best practices in place yet.
+If you're considering using Pinia please drop a message in the `#frontend` internal Slack channel for evaluation.
+
+[Pinia](https://pinia.vuejs.org/) is Vue's recommended client-side state management tool.
+[Learn more about Pinia at GitLab](pinia.md).
+
+### Strengths
+
+- Simple but robust
+- Lightweight at ≈1.5kb (as quoted by the Pinia site)
+- Vue reactivity under the hood, API similar to Vuex
+- Easy to debug
+
+### Weaknesses
+
+- Can't do any advanced GraphQL request handling out of the box (data normalization, polling, caching, etc.)
+- Can lead to same pitfalls as Vuex without guidance (overblown stores)
+
+### Pick Pinia when you have any of these
+
+- Significant percentage of Vue application state is client-side state
+- Migrating from Vuex is a high priority
+- You're not considering using Apollo for client state management
+
+## Combining Pinia and Apollo
+
+We recommend you pick either Apollo or Pinia as the only state manager in your app.
+Combining them is not recommended because:
+
+- Pinia and Apollo are both global stores, which means sharing responsibilities and having two sources of truth.
+- Difference in mental models: Apollo is configuration based, Pinia is not. Switching between these mental models is tedious and error-prone.
+- Experiencing the drawbacks of both approaches.
+
+However there may be cases when it's OK to combine these two to seek specific benefits from both solutions:
+
+- If there's a significant percentage of client-side state that would be best managed in Pinia.
+- If domain-specific concerns warrant Apollo for cohesive GraphQL requests within a component.
+
+If you have to use both Apollo and Pinia, please follow these rules:
+
+- **Never use Apollo Client in Pinia stores**. Apollo Client should only be consumed within a Vue component or a [composable](vue.md#composables).
+- Do not sync data between Apollo and Pinia.
+- You should have only one source of truth for your requests.
+
+### Add Apollo to an existing app with Pinia
+
+You can have Apollo data management in your components alongside existing Pinia state when you both:
+
+- Need to work with data coming from GraphQL
+- Can't migrate from Pinia to Apollo because of high migration effort
+
+Don't try to manage client state (not to be confused with GraphQL or REST data) with Apollo and Pinia at the same time,
+consider migrating from Pinia to Apollo if you need this.
+Don't use Apollo inside Pinia stores.
+
+### Add Pinia to an existing app with Apollo
+
+Strongly consider [using Apollo for client-side state management](graphql.md#local-state-with-apollo) first. However, if all of the
+following are true, Apollo might not be the best tool for managing this client-side state:
+
+- If the footprint of client-side state is significant enough that there's a high implementation cost due to Apollo's complexities.
+- If the client-side state can be nicely decoupled from the Apollo managed GraphQL API data.
+
+### Vuex used alongside Apollo
+
+[Vuex is deprecated in GitLab](vuex.md#deprecated), use the guidance above to pick either Apollo or Pinia as your primary state manager.
+Follow the corresponding migration guide: [Apollo](migrating_from_vuex.md) or [Pinia](pinia.md#migrating-from-vuex).
+Do not add new Pinia stores on top of the existing Vuex store, migrate first.

doc/development/fe_guide/vue.md

@@ -41,12 +41,13 @@ In the past, we added interactivity to the page piece-by-piece, adding multiple
 
 Because of these reasons, we want to be cautious about adding new Vue applications to the pages where another Vue application is already present (this does not include old or new navigation). Before adding a new app, make sure that it is absolutely impossible to extend an existing application to achieve a desired functionality. When in doubt, feel free to ask for the architectural advise on `#frontend` or `#frontend-maintainers` Slack channel.
 
-If you still need to add a new application, make sure it shares local state with existing applications (preferably via Apollo Client, or Vuex if we use REST API)
+If you still need to add a new application, make sure it shares local state with existing applications.
+Learn: [How do I know which state manager to use?](state_management.md)
 
 ## Vue architecture
 
 The main goal we are trying to achieve with Vue architecture is to have only one data flow, and only one data entry.
-To achieve this goal we use [Vuex](#vuex) or [Apollo Client](graphql.md#libraries)
+To achieve this goal we use [Pinia](pinia.md) or [Apollo Client](graphql.md#libraries)
 
 You can also read about this architecture in Vue documentation about
 [state management](https://v2.vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch)
@@ -460,11 +461,13 @@ in one table would not be a good use of this pattern.
 
 You can read more about components in Vue.js site, [Component System](https://v2.vuejs.org/v2/guide/#Composing-with-Components).
 
-### A folder for the Store
+### Pinia
 
-#### Vuex
+[Learn more about Pinia in GitLab](pinia.md).
 
-Check this [page](vuex.md) for more details.
+### Vuex
+
+[Vuex is deprecated](vuex.md#deprecated), consider [migrating](migrating_from_vuex.md).
 
 ### Vue Router
 
@@ -567,8 +570,7 @@ Based on the Vue guidance:
 
 - **Do not** use or create a JavaScript class in your [data function](https://v2.vuejs.org/v2/api/#data).
 - **Do not** add new JavaScript class implementations.
-- **Do** use [GraphQL](../api_graphql_styleguide.md), [Vuex](vuex.md) or a set of components if
-  cannot use primitives or objects.
+- **Do** encapsulate complex state management with cohesive decoupled components or [a state manager](state_management.md).
 - **Do** maintain existing implementations using such approaches.
 - **Do** Migrate components to a pure object model when there are substantial changes to it.
 - **Do** add business logic to helpers or utilities, so you can test them separately from your component.
@@ -726,29 +728,6 @@ const useSomeLogic = (done) => {
 }
 ```
 
-#### Composables and Vuex
-
-We should always prefer to avoid using Vuex state in composables. In case it's not possible, we should use props to receive that state, and emit events from the `setup` to update the Vuex state. A parent component should be responsible to get that state from Vuex, and mutate it on events emitted from a child. You should **never mutate a state that's coming down from a prop**. If a composable must mutate a Vuex state, it should use a callback to emit an event.
-
-```javascript
-const useAsyncComposable = ({ state, update }) => {
-  const start = async () => {
-    const newState = await doSomething(state);
-    update(newState);
-  };
-  return { start };
-};
-
-const ComponentWithComposable = {
-  setup(props, { emit }) {
-    const update = (data) => emit('update', data);
-    const state = computed(() => props.state); // state from Vuex
-    const { start } = useAsyncComposable({ state, update });
-    start();
-  },
-};
-```
-
 #### Testing composables
 
 <!-- TBD -->
@@ -935,11 +914,10 @@ Using `trigger` on the component means we treat it as a white box: we assume tha
 
 You should only apply to be a Vue.js expert when your own merge requests and your reviews show:
 
-- 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#naming-pattern-request-and-receive-namespaces)
-- Knowledge about the existing Vue and Vuex applications and existing reusable components
+- Deep understanding of Vue reactivity
+- Vue and [Pinia](pinia.md) code are structured according to both official and our guidelines
+- Full understanding of testing Vue components and Pinia stores
+- Knowledge about the existing Vue and Pinia applications and existing reusable components
 
 ## Vue 2 -> Vue 3 Migration
 

doc/development/fe_guide/vuex.md

@@ -6,9 +6,12 @@ info: Any user with at least the Maintainer role can merge updates to this conte
 
 # Vuex
 
-[Vuex](https://vuex.vuejs.org) should no longer be considered a preferred path to store management and is currently in its legacy phase. This means it is acceptable to add upon existing `Vuex` stores, but we strongly recommend reducing store sizes over time and eventually [migrating away from VueX entirely](migrating_from_vuex.md). Before adding any new `Vuex` store to an application, first ensure that the `Vue` application you plan to add it into **does not use** `Apollo`. `Vuex` and `Apollo` should not be combined unless absolutely necessary. Consider reading through [our GraphQL documentation](../fe_guide/graphql.md) for more guidelines on how you can build `Apollo` based applications.
+## DEPRECATED
 
-The information included in this page is explained in more detail in the
+**[Vuex](https://vuex.vuejs.org) is deprecated at GitLab** and no new Vuex stores should be created.
+You can still maintain existing Vuex stores but we strongly recommend [migrating away from Vuex entirely](migrating_from_vuex.md).
+
+The rest of the information included on this page is explained in more detail in the
 official [Vuex documentation](https://vuex.vuejs.org).
 
 ## Separation of concerns