diff options
Diffstat (limited to 'doc/development/fe_guide')
48 files changed, 157 insertions, 72 deletions
diff --git a/doc/development/fe_guide/accessibility/automated_testing.md b/doc/development/fe_guide/accessibility/automated_testing.md index 2c0d598dc58..b7f50452802 100644 --- a/doc/development/fe_guide/accessibility/automated_testing.md +++ b/doc/development/fe_guide/accessibility/automated_testing.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Automated accessibility testing diff --git a/doc/development/fe_guide/accessibility/best_practices.md b/doc/development/fe_guide/accessibility/best_practices.md index 37c28f99116..d9186278643 100644 --- a/doc/development/fe_guide/accessibility/best_practices.md +++ b/doc/development/fe_guide/accessibility/best_practices.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Accessibility best practices diff --git a/doc/development/fe_guide/accessibility/index.md b/doc/development/fe_guide/accessibility/index.md index 5274fa644e1..fef97aadaa5 100644 --- a/doc/development/fe_guide/accessibility/index.md +++ b/doc/development/fe_guide/accessibility/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Accessibility diff --git a/doc/development/fe_guide/architecture.md b/doc/development/fe_guide/architecture.md index 810d9af2de7..971c527ef68 100644 --- a/doc/development/fe_guide/architecture.md +++ b/doc/development/fe_guide/architecture.md @@ -1,16 +1,65 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Architecture -When building new features, consider reaching out to relevant stakeholders as early as possible in the process. +At GitLab, there are no dedicated "software architects". Everyone is encouraged to make their own decisions and document them appropriately. To know how or where to document these decisions, read on. -Architectural decisions should be accessible to everyone. Document -them in the relevant Merge Request discussions or by updating our documentation -when appropriate by adding an entry to this section. +## Documenting decisions + +When building new features, consider the scope and scale of what you are about to build. Depending on the answer, there are several tools or processes that could support your endeavor. We aim to keep the process of building features as efficient as possible. As a general rule, use the simplest process possible unless you need the additional support and structure of more time consuming solutions. + +### Merge requests + +When a change impacts is limited within a group or has a single contributor, the smallest possible documentation of architecture decisions is a commit and by extension a merge request (MR). MRs or commits can still be referenced even after they are merged, so it is vital to leave a good description, comments and commit messages to explain certain decisions in case it needs to be referenced later. Even a MR that is intended to be reviewed within a group should contain all relevant decision-making explicitly. + +### Architectural Issue + +When a unit of work starts to get big enough that it might impact an entire group's direction, it may be a good idea to create an architecture issue to discuss the technical direction. This process is informal and has no official requirements. Create an issue within the GitLab project where you can propose a plan for the work to be done and invite collaborators to refine the proposal with you. + +This structure allows the group to think through a proposed change, gather feedback and iterate. It also allows them to use the issue as a source of truth rather than a comments thread on the feature issue or the MRs themselves. Consider adding some kind of visual support (like a schema) to facilitate the discussion. For example, you can reference this [architectural issue of the CI/CD Catalog](https://gitlab.com/gitlab-org/gitlab/-/issues/393225). + +### Design Documents + +When the work ahead may affect more than a single group, stage or potentially an entirement department (for example, all of the Frontend team) then it is likely that there is need for a [Design Document](https://about.gitlab.com/handbook/engineering/architecture/workflow/). + +This is well documented in the handbook, but to touch on it shortly, it is **the best way** to propose large changes and gather the required feedback and support to move forward. These documents are version controlled, keep evolving with time and are a great way to share a complex understanding across the entire organization. They also require a coach, which is a great way to involve someone with a lot of experience with larger changes. This process is shared across all engineering departments and is owned by the CTO. + +To see all Design Documents, you can check the [Architecture at GitLab page](../../architecture/index.md) + +### Frontend RFCs (deprecated) + +In the past, we had a [Frontend RFC project](https://gitlab.com/gitlab-org/frontend/rfcs) which goal was to propose larger changes and get opinions from the entire department. This project is no longer used for a couple of reasons: + +1. Issues created in this project had a very low participation rate (less than 20%) +1. Controversial issues would stall with no clear way to resolve them +1. Issues that were completed often did not need a RFC in the first place (small issues) +1. Changes were often proposed "naively" without clear time and resource allocation + +In most instances where we would have created a RFC, a Design Document can be used instead as it will have it's own RFC attached to it. This makes the conversation centered around the technical design and RFCs are just a way to further the completion of the design. + +### Entry in the Frontend documentation + +Adding an architecture section to the docs is a way to tell frontend engineers how to use or build upon an existing architecture. Use it to help "onboard" engineers to a part of the application that may not be self-evident. Try to avoid documenting your group's architecture here if it has no impact on other teams. + +### Which to choose? + +As a general rule, the wider the scope of your change, the more likely it is that you and your team would benefit from a Design Document. Also consider whether your change is a true two-way door decision: changes that can easily be reverted require less thinking ahead than those that cannot. + +Work that can be achieved within a single milestone probably only needs Merge requests. Work that may take several milestone to complete, but where you are the only DRI is probably also easier done through MRs. + +When multiple DRIs are involved, ask yourself if the work ahead is clear for all of you. If the work you do is complex and affects each others, consider gathering technical feedback from your team before you start working on an Architectural issue. Write a clear proposal, involve all stakeholders early and keep yourselves accountable to the decisions made on the issue. + +Very small changes may have a very broad impact. For example, a change to any ESLint rule will impact all of engineering, but might not require a Design Document. Consider sending your proposal through Slack to gauge interest ("Should we enable X rule?") and then simply create a MR. Finally, share widely to the appropriate channels to gather feedback. + +For recommending certain code patterns in our documentation, you can write the MR that apply your proposed change, share it broadly with the department and if no strong objections are raised, merge your change. This is more efficient than RFCs because of the bias for action, while also gathering all the feedback necessary for everyone to feel included. + +If you'd like to propose a major change to the technological stack (Vue to React, JavaScript to TypeScript, etc.), start by reaching out on Slack to gauge interest. Always ask yourself whether or not the problems that you see can be fixed from our current tech stack, as we should always try to fix our problems with the tools we already have. Other departments, such as Backend and QA, do not have a clear process to propose technological changes either. That is because these changes would require huge investements from the company and probably cannot be decided without involving high-ranking executives from engineering. + +Instead, consider starting a Design Document that explains the problem and try to solve it with our current tools. Invite contribution from the department and research this thoroughly as there can only be two outcomes. Either the problem **can** be solved with our current tools or it cannot. If it can, this is a huge with for our teams since we've fixed and issue without the need to completly change our stack, and if it cannot, then the Design Document can be the start of the larger conversation around the technological change. ## Widget Architecture diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md index 876855b807c..57d8bb39321 100644 --- a/doc/development/fe_guide/axios.md +++ b/doc/development/fe_guide/axios.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Axios diff --git a/doc/development/fe_guide/content_editor.md b/doc/development/fe_guide/content_editor.md index fdeabc99ea4..7a76b39edbc 100644 --- a/doc/development/fe_guide/content_editor.md +++ b/doc/development/fe_guide/content_editor.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Rich text editor development guidelines diff --git a/doc/development/fe_guide/customizable_dashboards.md b/doc/development/fe_guide/customizable_dashboards.md index be0794b95d0..93b5b20b047 100644 --- a/doc/development/fe_guide/customizable_dashboards.md +++ b/doc/development/fe_guide/customizable_dashboards.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Product Analytics -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Customizable dashboards @@ -206,7 +206,8 @@ export default { ## Dashboard designer -> Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default. +> - Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/411407) in GitLab 16.6. Feature flag `combined_analytics_dashboards_editor` removed. The dashboard designer provides a graphical interface for users to modify the panels and add new ones on user-defined dashboards. Is is not available on diff --git a/doc/development/fe_guide/dark_mode.md b/doc/development/fe_guide/dark_mode.md index 185bd60dd9a..3af65edf317 100644 --- a/doc/development/fe_guide/dark_mode.md +++ b/doc/development/fe_guide/dark_mode.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- This page is about developing dark mode for GitLab. For more information on how to enable dark mode, see [Change the syntax highlighting theme](../../user/profile/preferences.md#change-the-syntax-highlighting-theme). diff --git a/doc/development/fe_guide/dependencies.md b/doc/development/fe_guide/dependencies.md index b9bacada499..0ba38c04d7b 100644 --- a/doc/development/fe_guide/dependencies.md +++ b/doc/development/fe_guide/dependencies.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Frontend dependencies diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md index 44238ff5dc5..b8be003776f 100644 --- a/doc/development/fe_guide/design_patterns.md +++ b/doc/development/fe_guide/design_patterns.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Design Patterns diff --git a/doc/development/fe_guide/design_tokens.md b/doc/development/fe_guide/design_tokens.md index b47c2661e19..1556602e298 100644 --- a/doc/development/fe_guide/design_tokens.md +++ b/doc/development/fe_guide/design_tokens.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Design tokens diff --git a/doc/development/fe_guide/emojis.md b/doc/development/fe_guide/emojis.md index c93e1bb34c5..f1e4c55f985 100644 --- a/doc/development/fe_guide/emojis.md +++ b/doc/development/fe_guide/emojis.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Emojis diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index ab75cc27b6a..b8e98b47cac 100644 --- a/doc/development/fe_guide/frontend_faq.md +++ b/doc/development/fe_guide/frontend_faq.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Frontend FAQ diff --git a/doc/development/fe_guide/frontend_goals.md b/doc/development/fe_guide/frontend_goals.md index 4f39e82c72e..d2ae9ceff28 100644 --- a/doc/development/fe_guide/frontend_goals.md +++ b/doc/development/fe_guide/frontend_goals.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Frontend Goals diff --git a/doc/development/fe_guide/getting_started.md b/doc/development/fe_guide/getting_started.md index 14e704d567e..5687d912de3 100644 --- a/doc/development/fe_guide/getting_started.md +++ b/doc/development/fe_guide/getting_started.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Getting started diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 5807c9c5621..22b977519be 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +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. --- # GraphQL @@ -105,7 +104,7 @@ Default client accepts two parameters: `resolvers` and `config`. ### Multiple client queries for the same object -If you are making multiple queries to the same Apollo client object you might encounter the following error: `Cache data may be lost when replacing the someProperty field of a Query object. To address this problem, either ensure all objects of SomeEntityhave an id or a custom merge function`. We are already checking `id` presence for every GraphQL type that has an `id`, so this shouldn't be the case (unless you see this warning when running unit tests; in this case please ensure your mocked responses contain an `id` whenever it's requested). +If you are making multiple queries to the same Apollo client object you might encounter the following error: `Cache data may be lost when replacing the someProperty field of a Query object. To address this problem, either ensure all objects of SomeEntityhave an id or a custom merge function`. We are already checking `id` presence for every GraphQL type that has an `id`, so this shouldn't be the case (unless you see this warning when running unit tests; in this case ensure your mocked responses contain an `id` whenever it's requested). When `SomeEntity` type doesn't have an `id` property in the GraphQL schema, to fix this warning we need to define a custom merge function. @@ -974,6 +973,31 @@ const data = store.readQuery({ Read more about the `@connection` directive in [Apollo's documentation](https://www.apollographql.com/docs/react/caching/advanced-topics/#the-connection-directive). +### Batching similar queries + +By default, the Apollo client sends one HTTP request from the browser per query. You can choose to +batch several queries in a single outgoing request and lower the number of requests by defining a +[batchKey](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http/#batchkey). + +This can be helpful when a query is called multiple times from the same component but you +want to update the UI once. In this example we use the component name as the key: + +```javascript +export default { + name: 'MyComponent' + apollo: { + user: { + query: QUERY_IMPORT, + context: { + batchKey: 'MyComponent', + }, + } + }, +}; +``` + +The batch key can be the name of the component. + #### Polling and Performance While the Apollo client has support for simple polling, for performance reasons, our [ETag-based caching](../polling.md) is preferred to hitting the database each time. diff --git a/doc/development/fe_guide/guides.md b/doc/development/fe_guide/guides.md index dc2fffcf10a..ce53d3df0fc 100644 --- a/doc/development/fe_guide/guides.md +++ b/doc/development/fe_guide/guides.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Guides diff --git a/doc/development/fe_guide/haml.md b/doc/development/fe_guide/haml.md index 1dc8cf63de9..88f4a785a70 100644 --- a/doc/development/fe_guide/haml.md +++ b/doc/development/fe_guide/haml.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # HAML diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index df296f13f48..d1882644c02 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Icons and SVG Illustrations diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 6bea22bd6bf..40ff704edfa 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Frontend Development Guidelines @@ -11,7 +11,7 @@ across the GitLab frontend team. ## Overview -GitLab is built on top of [Ruby on Rails](https://rubyonrails.org). It uses [Haml](https://haml.info/) and a JavaScript-based frontend with [Vue.js](https://vuejs.org). If you are not sure when to use Vue on top of Haml-page, please read [this explanation](vue.md#when-to-add-vue-application). +GitLab is built on top of [Ruby on Rails](https://rubyonrails.org). It uses [Haml](https://haml.info/) and a JavaScript-based frontend with [Vue.js](https://vuejs.org). If you are not sure when to use Vue on top of Haml-page, read [this explanation](vue.md#when-to-add-vue-application). <!-- vale gitlab.Spelling = NO --> @@ -19,19 +19,19 @@ Be wary of [the limitations that come with using Hamlit](https://github.com/k0ku <!-- vale gitlab.Spelling = YES --> -When it comes to CSS, we use a utils-based CSS approach. GitLab has its own CSS utils which are packaged inside the `gitlab-ui` project and can be seen [in the repository](https://gitlab.com/gitlab-org/gitlab-ui/-/tree/main/src/scss/utility-mixins) or on [UNPKG](https://unpkg.com/browse/@gitlab/ui@latest/src/scss/utility-mixins/). Please favor using these before adding or using any SCSS classes. +When it comes to CSS, we use a utils-based CSS approach. GitLab has its own CSS utils which are packaged inside the `gitlab-ui` project and can be seen [in the repository](https://gitlab.com/gitlab-org/gitlab-ui/-/tree/main/src/scss/utility-mixins) or on [UNPKG](https://unpkg.com/browse/@gitlab/ui@latest/src/scss/utility-mixins/). Favor using these before adding or using any SCSS classes. 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/index.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 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. 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 copy strings and translations, we have frontend utilities available. Please see the JavaScript section of [Preparing a page for translation](../i18n/externalization.md#javascript-files) for more information. +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. Working with our frontend assets requires Node (v12.22.1 or greater) and Yarn (v1.10.0 or greater). You can find information on how to install these on our diff --git a/doc/development/fe_guide/keyboard_shortcuts.md b/doc/development/fe_guide/keyboard_shortcuts.md index aeeee72e6be..35ca240a2ad 100644 --- a/doc/development/fe_guide/keyboard_shortcuts.md +++ b/doc/development/fe_guide/keyboard_shortcuts.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Implementing keyboard shortcuts diff --git a/doc/development/fe_guide/logging.md b/doc/development/fe_guide/logging.md index 750bf95e8b2..debe9cad27d 100644 --- a/doc/development/fe_guide/logging.md +++ b/doc/development/fe_guide/logging.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Client-side logging for frontend development diff --git a/doc/development/fe_guide/merge_request_widget_extensions.md b/doc/development/fe_guide/merge_request_widget_extensions.md index 99206d99590..5319048dfa5 100644 --- a/doc/development/fe_guide/merge_request_widget_extensions.md +++ b/doc/development/fe_guide/merge_request_widget_extensions.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Merge request widget extensions diff --git a/doc/development/fe_guide/migrating_from_vuex.md b/doc/development/fe_guide/migrating_from_vuex.md index 8dca744e192..45a1ea0b7ee 100644 --- a/doc/development/fe_guide/migrating_from_vuex.md +++ b/doc/development/fe_guide/migrating_from_vuex.md @@ -1,14 +1,14 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Migrating from Vuex ## Why? -We have defined [GraphQL as our primary API](../../api/graphql/index.md#vision) for all user-facing features, +We have defined the [GraphQL API](../../api/graphql/index.md) as [the primary API](../api_graphql_styleguide.md#vision) for all user-facing features, so we can safely assume that whenever GraphQL is present, so will the Apollo Client. We [do not want to use Vuex with Apollo](graphql.md#using-with-vuex), so the VueX stores count will naturally decline over time as we move from the REST API to GraphQL. diff --git a/doc/development/fe_guide/onboarding_course/index.md b/doc/development/fe_guide/onboarding_course/index.md index 0b0ffc69f1b..d8d4cdad8a6 100644 --- a/doc/development/fe_guide/onboarding_course/index.md +++ b/doc/development/fe_guide/onboarding_course/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Foundations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Frontend onboarding course @@ -46,7 +46,7 @@ A fortnightly 1-on-1 mentoring sessions are also available to each participant. There are 10 places available on the course. The date will be set after the course material has been prepared. -Please complete the [Frontend Onboarding Course Application Form](https://forms.gle/39Rs4w4ZxQuByhE4A) to apply. +Complete the [Frontend Onboarding Course Application Form](https://forms.gle/39Rs4w4ZxQuByhE4A) to apply. You may also participate in the course informally at your own pace, without the benefit of the synchronous office hours or mentoring session. GitLab team members are happy to support you regardless. diff --git a/doc/development/fe_guide/onboarding_course/lesson_1.md b/doc/development/fe_guide/onboarding_course/lesson_1.md index e82d350f854..ec26da8c4eb 100644 --- a/doc/development/fe_guide/onboarding_course/lesson_1.md +++ b/doc/development/fe_guide/onboarding_course/lesson_1.md @@ -1,7 +1,7 @@ --- stage: manage group: foundations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Lesson 1 diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 5e8581663b6..aedb391ed25 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Performance diff --git a/doc/development/fe_guide/registry_architecture.md b/doc/development/fe_guide/registry_architecture.md index cf267e80619..bc46c2643de 100644 --- a/doc/development/fe_guide/registry_architecture.md +++ b/doc/development/fe_guide/registry_architecture.md @@ -1,7 +1,7 @@ --- stage: Package group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Registry architecture @@ -12,8 +12,8 @@ already exists to unify the user and developer experiences. Existing registries: -- Package Registry -- Container Registry +- Package registry +- Container registry - Terraform Module Registry - Dependency Proxy @@ -82,7 +82,7 @@ main pieces of the desired UI and UX of a registry page. The most important comp When adding a new registry: - Leverage the shared components that already exist. It's good to look at how the components are - structured and used in the more mature registries (for example, the Package Registry). + structured and used in the more mature registries (for example, the package registry). - If it's in line with the backend requirements, we suggest using GraphQL for the API. This helps in dealing with the innate performance issue of registries. - If possible, we recommend using [Vue Router](https://v3.router.vuejs.org/) diff --git a/doc/development/fe_guide/security.md b/doc/development/fe_guide/security.md index 4e06c22b383..e4b748f7e7c 100644 --- a/doc/development/fe_guide/security.md +++ b/doc/development/fe_guide/security.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Security diff --git a/doc/development/fe_guide/sentry.md b/doc/development/fe_guide/sentry.md index 95a170b7976..fa85d51afb0 100644 --- a/doc/development/fe_guide/sentry.md +++ b/doc/development/fe_guide/sentry.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Sentry monitoring in the frontend development of GitLab diff --git a/doc/development/fe_guide/source_editor.md b/doc/development/fe_guide/source_editor.md index 943ac2969f3..e65ede53a13 100644 --- a/doc/development/fe_guide/source_editor.md +++ b/doc/development/fe_guide/source_editor.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Source Editor diff --git a/doc/development/fe_guide/storybook.md b/doc/development/fe_guide/storybook.md index cbda9d5efa2..05d4397933f 100644 --- a/doc/development/fe_guide/storybook.md +++ b/doc/development/fe_guide/storybook.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Storybook diff --git a/doc/development/fe_guide/style/html.md b/doc/development/fe_guide/style/html.md index 9d8809f19c7..c9168a68614 100644 --- a/doc/development/fe_guide/style/html.md +++ b/doc/development/fe_guide/style/html.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # HTML style guide diff --git a/doc/development/fe_guide/style/index.md b/doc/development/fe_guide/style/index.md index 552b769d6f6..31b5db82153 100644 --- a/doc/development/fe_guide/style/index.md +++ b/doc/development/fe_guide/style/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Frontend style guides diff --git a/doc/development/fe_guide/style/javascript.md b/doc/development/fe_guide/style/javascript.md index cccaefe8a19..01caf65be5f 100644 --- a/doc/development/fe_guide/style/javascript.md +++ b/doc/development/fe_guide/style/javascript.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # JavaScript style guide diff --git a/doc/development/fe_guide/style/scss.md b/doc/development/fe_guide/style/scss.md index 400b178d9a4..a78fcf67665 100644 --- a/doc/development/fe_guide/style/scss.md +++ b/doc/development/fe_guide/style/scss.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # SCSS style guide diff --git a/doc/development/fe_guide/style/typescript.md b/doc/development/fe_guide/style/typescript.md index 529459097b4..567b80489fb 100644 --- a/doc/development/fe_guide/style/typescript.md +++ b/doc/development/fe_guide/style/typescript.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # TypeScript diff --git a/doc/development/fe_guide/style/vue.md b/doc/development/fe_guide/style/vue.md index a3ab1c1af30..83d725d453b 100644 --- a/doc/development/fe_guide/style/vue.md +++ b/doc/development/fe_guide/style/vue.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Vue.js style guide diff --git a/doc/development/fe_guide/tech_stack.md b/doc/development/fe_guide/tech_stack.md index 9c0d50ea7bd..87a5e42f75e 100644 --- a/doc/development/fe_guide/tech_stack.md +++ b/doc/development/fe_guide/tech_stack.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Tech Stack diff --git a/doc/development/fe_guide/tips_and_tricks.md b/doc/development/fe_guide/tips_and_tricks.md index dcacdb8387b..ae19ecd3fe5 100644 --- a/doc/development/fe_guide/tips_and_tricks.md +++ b/doc/development/fe_guide/tips_and_tricks.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Tips and tricks diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md index c1084ab4453..536cf5c4a2a 100644 --- a/doc/development/fe_guide/tooling.md +++ b/doc/development/fe_guide/tooling.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Tooling diff --git a/doc/development/fe_guide/troubleshooting.md b/doc/development/fe_guide/troubleshooting.md index 3e4c5007b64..743eaf7e494 100644 --- a/doc/development/fe_guide/troubleshooting.md +++ b/doc/development/fe_guide/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Troubleshooting frontend development issues diff --git a/doc/development/fe_guide/type_hinting.md b/doc/development/fe_guide/type_hinting.md index 026bf855e27..0252b5343d4 100644 --- a/doc/development/fe_guide/type_hinting.md +++ b/doc/development/fe_guide/type_hinting.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Type hinting overview diff --git a/doc/development/fe_guide/view_component.md b/doc/development/fe_guide/view_component.md index cfd78597501..a616a3d7c48 100644 --- a/doc/development/fe_guide/view_component.md +++ b/doc/development/fe_guide/view_component.md @@ -1,7 +1,7 @@ --- stage: Manage group: Foundations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # ViewComponent diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index cfc3ac466d5..69967a5a2be 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Vue @@ -39,9 +39,9 @@ In the past, we added interactivity to the page piece-by-piece, adding multiple - multiple applications lead to unpredictable user experience, increased page complexity, harder debugging process; - the way apps communicate with each other affects Web Vitals numbers. -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, please make sure that it is absolutely impossible to extend an existing application to achieve a desired functionality. When in doubt, please feel free to ask for the architectural advise on `#frontend` or `#frontend-maintainers` Slack channel. +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, please 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 (preferably via Apollo Client, or Vuex if we use REST API) ## Vue architecture @@ -860,7 +860,7 @@ component under test, with the `computed` property, for example). Remember to us We should test for events emitted in response to an action in our component. This testing verifies the correct events are being fired with the correct arguments. -For any DOM events we should use [`trigger`](https://v1.test-utils.vuejs.org/api/wrapper/#trigger) +For any native DOM events we should use [`trigger`](https://v1.test-utils.vuejs.org/api/wrapper/#trigger) to fire out event. ```javascript @@ -892,6 +892,20 @@ it('should fire the itemClicked event', () => { We should verify an event has been fired by asserting against the result of the [`emitted()`](https://v1.test-utils.vuejs.org/api/wrapper/#emitted) method. +It is a good practice to prefer to use `vm.$emit` over `trigger` when emitting events from child components. + +Using `trigger` on the component means we treat it as a white box: we assume that the root element of child component has a native `click` event. Also, some tests fail in Vue3 mode when using `trigger` on child components. + + ```javascript + const findButton = () => wrapper.findComponent(GlButton); + + // bad + findButton().trigger('click'); + + // good + findButton().vm.$emit('click'); + ``` + ## Vue.js Expert Role You should only apply to be a Vue.js expert when your own merge requests and your reviews show: diff --git a/doc/development/fe_guide/vue3_migration.md b/doc/development/fe_guide/vue3_migration.md index b9e819a95bd..6eb1d4c2413 100644 --- a/doc/development/fe_guide/vue3_migration.md +++ b/doc/development/fe_guide/vue3_migration.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Migration to Vue 3 diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 06d7070b855..aff3588a503 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -1,12 +1,12 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # 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. Please consider reading through [our GraphQL documentation](../fe_guide/graphql.md) for more guidelines on how you can build `Apollo` based applications. +[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. The information included in this page is explained in more detail in the official [Vuex documentation](https://vuex.vuejs.org). diff --git a/doc/development/fe_guide/widgets.md b/doc/development/fe_guide/widgets.md index 6cd8e6c091c..de4ac7620c2 100644 --- a/doc/development/fe_guide/widgets.md +++ b/doc/development/fe_guide/widgets.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +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. --- # Widgets |