Add latest changes from gitlab-org/gitlab@master

17 files changed, 330 insertions, 322 deletions

diff --git a/doc/development/README.md b/doc/development/README.md
index bc996fdff21..5ab8653dc35 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -1,308 +1,8 @@
 ---
-comments: false
-type: index, dev
-stage: none
-group: Development
-info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
-description: "Development Guidelines: learn how to contribute to GitLab."
+redirect_to: 'index.md'
 ---
 
-# Contributor and Development Docs
+This document was moved to [another location](index.md).
 
-Learn the processes and technical information needed for contributing to GitLab.
-
-This content is intended for members of the GitLab Team as well as community
-contributors. Content specific to the GitLab Team should instead be included in
-the [Handbook](https://about.gitlab.com/handbook/).
-
-For information on using GitLab to work on your own software projects, see the
-[GitLab user documentation](../user/index.md).
-
-For information on working with the GitLab APIs, see the [API documentation](../api/README.md).
-
-For information about how to install, configure, update, and upgrade your own
-GitLab instance, see the [administration documentation](../administration/index.md).
-
-## Get started
-
-- Set up the GitLab development environment with the
-  [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/README.md)
-- [GitLab contributing guide](contributing/index.md)
-  - [Issues workflow](contributing/issue_workflow.md) for more information about:
-    - Issue tracker guidelines.
-    - Triaging.
-    - Labels.
-    - Feature proposals.
-    - Issue weight.
-    - Regression issues.
-    - Technical or UX debt.
-  - [Merge requests workflow](contributing/merge_request_workflow.md) for more
-    information about:
-    - Merge request guidelines.
-    - Contribution acceptance criteria.
-    - Definition of done.
-    - Dependencies.
-  - [Style guides](contributing/style_guides.md)
-  - [Implement design & UI elements](contributing/design.md)
-- [GitLab Architecture Overview](architecture.md)
-- [Rake tasks](rake_tasks.md) for development
-
-## Processes
-
-**Must-reads:**
-
-- [Guide on adapting existing and introducing new components](architecture.md#adapting-existing-and-introducing-new-components)
-- [Code review guidelines](code_review.md) for reviewing code and having code
-  reviewed
-- [Database review guidelines](database_review.md) for reviewing
-  database-related changes and complex SQL queries, and having them reviewed
-- [Secure coding guidelines](secure_coding_guidelines.md)
-- [Pipelines for the GitLab project](pipelines.md)
-
-Complementary reads:
-
-- [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md)
-- [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer)
-- [Guidelines for implementing Enterprise Edition features](ee_features.md)
-- [Danger bot](dangerbot.md)
-- [Guidelines for changelogs](changelog.md)
-- [Requesting access to ChatOps on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLab team members)
-- [Patch release process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/patch/process.md#process-for-developers)
-- [Adding a new service component to GitLab](adding_service_component.md)
-
-### Development guidelines review
-
-When you submit a change to the GitLab development guidelines, who
-you ask for reviews depends on the level of change.
-
-#### Wording, style, or link changes
-
-Not all changes require extensive review. For example, MRs that don't change the
-content's meaning or function can be reviewed, approved, and merged by any
-maintainer or Technical Writer. These can include:
-
-- Typo fixes.
-- Clarifying links, such as to external programming language documentation.
-- Changes to comply with the [Documentation Style Guide](documentation/index.md)
-  that don't change the intent of the documentation page.
-
-#### Specific changes
-
-If the MR proposes changes that are limited to a particular stage, group, or team,
-request a review and approval from an experienced GitLab Team Member in that
-group. For example, if you're documenting a new internal API used exclusively by
-a given group, request an engineering review from one of the group's members.
-
-After the engineering review is complete, assign the MR to the
-[Technical Writer associated with the stage and group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)
-in the modified documentation page's metadata.
-
-If you have questions or need further input, request a review from the
-Technical Writer assigned to the [Development Guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines).
-
-#### Broader changes
-
-Some changes affect more than one group. For example:
-
-- Changes to [code review guidelines](code_review.md).
-- Changes to [commit message guidelines](contributing/merge_request_workflow.md#commit-messages-guidelines).
-- Changes to guidelines in [feature flags in development of GitLab](feature_flags/).
-- Changes to [feature flags documentation guidelines](documentation/feature_flags.md).
-
-In these cases, use the following workflow:
-
-1. Request a peer review from a member of your team.
-1. Request a review and approval of an Engineering Manager (EM)
-   or Staff Engineer who's responsible for the area in question:
-
-   - [Frontend](https://about.gitlab.com/handbook/engineering/frontend/)
-   - [Backend](https://about.gitlab.com/handbook/engineering/)
-   - [Database](https://about.gitlab.com/handbook/engineering/development/database/)
-   - [User Experience (UX)](https://about.gitlab.com/handbook/engineering/ux/)
-   - [Security](https://about.gitlab.com/handbook/engineering/security/)
-   - [Quality](https://about.gitlab.com/handbook/engineering/quality/)
-     - [Engineering Productivity](https://about.gitlab.com/handbook/engineering/quality/engineering-productivity-team/)
-   - [Infrastructure](https://about.gitlab.com/handbook/engineering/infrastructure/)
-   - [Technical Writing](https://about.gitlab.com/handbook/engineering/ux/technical-writing/)
-
-   You can skip this step for MRs authored by EMs or Staff Engineers responsible
-   for their area.
-
-   If there are several affected groups, you may need approvals at the
-   EM/Staff Engineer level from each affected area.
-
-1. After completing the reviews, consult with the EM/Staff Engineer
-   author / approver of the MR.
-
-   If this is a significant change across multiple areas, request final review
-   and approval from the VP of Development, the DRI for Development Guidelines,
-   @clefelhocz1.
-
-1. After all approvals are complete, assign the merge request to the
-   Technical Writer for [Development Guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines)
-   for final content review and merge. The Technical Writer may ask for
-   additional approvals as previously suggested before merging the MR.
-
-## UX and Frontend guides
-
-- [GitLab Design System](https://design.gitlab.com/), for building GitLab with
-  existing CSS styles and elements
-- [Frontend guidelines](fe_guide/index.md)
-- [Emoji guide](fe_guide/emojis.md)
-
-## Backend guides
-
-- [Directory structure](directory_structure.md)
-- [GitLab utilities](utilities.md)
-- [Issuable-like Rails models](issuable-like-models.md)
-- [Logging](logging.md)
-- [API style guide](api_styleguide.md) for contributing to the API
-- [GraphQL API style guide](api_graphql_styleguide.md) for contributing to the
-  [GraphQL API](../api/graphql/index.md)
-- [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers
-- [Working with Gitaly](gitaly.md)
-- [Manage feature flags](feature_flags/index.md)
-- [Licensed feature availability](licensed_feature_availability.md)
-- [Dealing with email/mailers](emails.md)
-- [Shell commands](shell_commands.md) in the GitLab codebase
-- [`Gemfile` guidelines](gemfile.md)
-- [Pry debugging](pry_debugging.md)
-- [Sidekiq debugging](../administration/troubleshooting/sidekiq.md)
-- [Accessing session data](session.md)
-- [Gotchas](gotchas.md) to avoid
-- [Avoid modules with instance variables](module_with_instance_variables.md), if
-  possible
-- [How to dump production data to staging](db_dump.md)
-- [Working with the GitHub importer](github_importer.md)
-- [Import/Export development documentation](import_export.md)
-- [Test Import Project](import_project.md)
-- [Group migration](bulk_import.md)
-- [Elasticsearch integration docs](elasticsearch.md)
-- [Working with Merge Request diffs](diffs.md)
-- [Kubernetes integration guidelines](kubernetes.md)
-- [Permissions](permissions.md)
-- [Guidelines for reusing abstractions](reusing_abstractions.md)
-- [DeclarativePolicy framework](policies.md)
-- [How Git object deduplication works in GitLab](git_object_deduplication.md)
-- [Geo development](geo.md)
-- [Routing](routing.md)
-- [Repository mirroring](repository_mirroring.md)
-- [Git LFS](lfs.md)
-- [Developing against interacting components or features](interacting_components.md)
-- [File uploads](uploads.md)
-- [Auto DevOps development guide](auto_devops.md)
-- [Mass Inserting Models](mass_insert.md)
-- [Value Stream Analytics development guide](value_stream_analytics.md)
-- [Issue types vs first-class types](issue_types.md)
-- [Application limits](application_limits.md)
-- [Redis guidelines](redis.md)
-- [Rails initializers](rails_initializers.md)
-- [Code comments](code_comments.md)
-- [Renaming features](renaming_features.md)
-- [Windows Development on GCP](windows.md)
-- [Code Intelligence](code_intelligence/index.md)
-- [Approval Rules](approval_rules.md)
-- [Feature categorization](feature_categorization/index.md)
-- [Wikis development guide](wikis.md)
-- [Newlines style guide](newlines_styleguide.md)
-- [Image scaling guide](image_scaling.md)
-- [Export to CSV](export_csv.md)
-- [Cascading Settings](cascading_settings.md)
-- [FIPS compliance](fips_compliance.md)
-
-## Performance guides
-
-- [Instrumentation](instrumentation.md) for Ruby code running in production
-  environments.
-- [Performance guidelines](performance.md) for writing code, benchmarks, and
-  certain patterns to avoid.
-- [Merge request performance guidelines](merge_request_performance_guidelines.md)
-  for ensuring merge requests do not negatively impact GitLab performance
-- [Profiling](profiling.md) a URL, measuring performance using Sherlock, or
-  tracking down N+1 queries using Bullet.
-- [Cached queries guidelines](cached_queries.md), for tracking down N+1 queries
-  masked by query caching, memory profiling and why should we avoid cached
-  queries.
-
-## Database guides
-
-See [database guidelines](database/index.md).
-
-## Integration guides
-
-- [Jira Connect app](integrations/jira_connect.md)
-- [Security Scanners](integrations/secure.md)
-- [Secure Partner Integration](integrations/secure_partner_integration.md)
-- [How to run Jenkins in development environment](integrations/jenkins.md)
-- [How to run local `Codesandbox` integration for Web IDE Live Preview](integrations/codesandbox.md)
-
-## Testing guides
-
-- [Testing standards and style guidelines](testing_guide/index.md)
-- [Frontend testing standards and style guidelines](testing_guide/frontend_testing.md)
-
-## Refactoring guides
-
-- [Refactoring guidelines](refactoring_guide/index.md)
-
-## Deprecation guides
-
-- [Deprecation guidelines](deprecation_guidelines/index.md)
-
-## Documentation guides
-
-- [Writing documentation](documentation/index.md)
-- [Documentation style guide](documentation/styleguide/index.md)
-- [Markdown](../user/markdown.md)
-
-## Internationalization (i18n) guides
-
-- [Introduction](i18n/index.md)
-- [Externalization](i18n/externalization.md)
-- [Translation](i18n/translation.md)
-
-## Product Intelligence guides
-
-- [Product Intelligence guide](https://about.gitlab.com/handbook/product/product-intelligence-guide/)
-- [Usage Ping guide](usage_ping/index.md)
-- [Snowplow guide](snowplow/index.md)
-
-## Experiment guide
-
-- [Introduction](experiment_guide/index.md)
-
-## Build guides
-
-- [Building a package for testing purposes](build_test_package.md)
-
-## Compliance
-
-- [Licensing](licensing.md) for ensuring license compliance
-
-## Go guides
-
-- [Go Guidelines](go_guide/index.md)
-
-## Shell Scripting guides
-
-- [Shell scripting standards and style guidelines](shell_scripting_guide/index.md)
-
-## Domain-specific guides
-
-- [CI/CD development documentation](cicd/index.md)
-- [AppSec development documentation](appsec/index.md)
-
-## Other Development guides
-
-- [Defining relations between files using projections](projections.md)
-- [Reference processing](reference_processing.md)
-- [Compatibility with multiple versions of the application running at the same time](multi_version_compatibility.md)
-- [Features inside `.gitlab/`](features_inside_dot_gitlab.md)
-- [Dashboards for stage groups](stage_group_dashboards.md)
-- [Preventing transient bugs](transient/prevention-patterns.md)
-
-## Other GitLab Development Kit (GDK) guides
-
-- [Run full Auto DevOps cycle in a GDK instance](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/auto_devops.md)
-- [Using GitLab Runner with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/runner.md)
-- [Using the Web IDE terminal with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/web_ide_terminal_gdk_setup.md)
+<!-- This redirect file can be deleted after 2021-09-28. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/development/changelog.md b/doc/development/changelog.md
index f0c37af42ab..e05428ea826 100644
--- a/doc/development/changelog.md
+++ b/doc/development/changelog.md
@@ -188,4 +188,4 @@ documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
 
 ---
 
-[Return to Development documentation](README.md)
+[Return to Development documentation](index.md)
diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md
index 6e3cdb59fd8..64a3c74db62 100644
--- a/doc/development/cicd/index.md
+++ b/doc/development/cicd/index.md
@@ -61,7 +61,7 @@ successfully or fail. Each status transition for job within a pipeline triggers
 looks for the next jobs to be transitioned towards completion. While doing that, `ProcessPipelineService`
 updates the status of jobs, stages and the overall pipeline.
 
-On the right side of the diagram we have a list of [runners](../../ci/runners/README.md)
+On the right side of the diagram we have a list of [runners](../../ci/runners/index.md)
 connected to the GitLab instance. These can be shared runners, group runners, or project-specific runners.
 The communication between runners and the Rails server occurs through a set of API endpoints, grouped as
 the `Runner API Gateway`.
diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md
index 8331985697e..eddaabe41d8 100644
--- a/doc/development/cicd/templates.md
+++ b/doc/development/cicd/templates.md
@@ -7,7 +7,7 @@ type: index, concepts, howto
 
 # Development guide for GitLab CI/CD templates
 
-This document explains how to develop [GitLab CI/CD templates](../../ci/examples/README.md).
+This document explains how to develop [GitLab CI/CD templates](../../ci/examples/index.md).
 
 ## Requirements for CI/CD templates
 
diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index df09b27c6b4..6f1d916fa78 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -644,4 +644,4 @@ Largely based on the [`thoughtbot` code review guide](https://github.com/thought
 
 ---
 
-[Return to Development documentation](README.md)
+[Return to Development documentation](index.md)
diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md
index 783cf7af6fc..9be89202d35 100644
--- a/doc/development/contributing/merge_request_workflow.md
+++ b/doc/development/contributing/merge_request_workflow.md
@@ -31,7 +31,7 @@ If you are new to GitLab development (or web development in general), see the
 some potentially easy issues.
 
 To start developing GitLab, download the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit)
-and see the [Development section](../../README.md) for the required guidelines.
+and see the [Development section](../../index.md) for the required guidelines.
 
 ## Merge request guidelines
 
diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md
index 68268027b73..3ecabd2d72d 100644
--- a/doc/development/dangerbot.md
+++ b/doc/development/dangerbot.md
@@ -58,7 +58,7 @@ itself, increasing visibility.
 
 ## Development guidelines
 
-Danger code is Ruby code, so all our [usual backend guidelines](README.md#backend-guides)
+Danger code is Ruby code, so all our [usual backend guidelines](index.md#backend-guides)
 continue to apply. However, there are a few things that deserve special emphasis.
 
 ### When to use Danger
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index 0f8c5f8e51f..14798b747c8 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -115,11 +115,11 @@ each page should have a metadata tag called `type`. It can be one or more of the
 following:
 
 - `index`: It consists mostly of a list of links to other pages.
-  [Example page](../../README.md).
+  [Example page](../../index.md).
 - `concepts`: The background or context of a subject.
   [Example page](../../topics/autodevops/index.md).
 - `howto`: Specific use case instructions.
-  [Example page](../../ssh/README.md).
+  [Example page](../../ssh/index.md).
 - `tutorial`: Learn a process/concept by doing.
   [Example page](../../gitlab-basics/start-using-git.md).
 - `reference`: A collection of information used as a reference to use a feature
@@ -395,7 +395,7 @@ This is preferred over static paths, as the helper also works on instances insta
 ### GitLab `/help` tests
 
 Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/features/help_pages_spec.rb)
-are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) works correctly from `/help`.
+are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../index.md) works correctly from `/help`.
 For example, [GitLab.com's `/help`](https://gitlab.com/help).
 
 ## Docs site architecture
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md
index 871fb26ce08..b2152858e8e 100644
--- a/doc/development/documentation/structure.md
+++ b/doc/development/documentation/structure.md
@@ -210,7 +210,7 @@ comments: false
 ---
 ```
 
-We're hiding comments only in main index pages, such as [the main documentation index](../../README.md),
+We're hiding comments only in main index pages, such as [the main documentation index](../../index.md),
 since its content is too broad to comment on. Before omitting Disqus, you must
 check with a technical writer.
 
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index fffb4d21a26..4c4e3755451 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -1495,7 +1495,7 @@ elements:
 
 ## GitLab versions
 
-GitLab product documentation pages (not including [Contributor and Development](../../README.md)
+GitLab product documentation pages (not including [Contributor and Development](../../index.md)
 pages in the `/development` directory) can include version information to help
 users be aware of recent improvements or additions.
 
diff --git a/doc/development/emails.md b/doc/development/emails.md
index 3e651a6efb8..c1054077f9e 100644
--- a/doc/development/emails.md
+++ b/doc/development/emails.md
@@ -141,4 +141,4 @@ Please note that `path/to/project` is used in GitLab as the handler for the Serv
 
 ---
 
-[Return to Development documentation](README.md)
+[Return to Development documentation](index.md)
diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md
index 2e814a9c41b..59ab3d41f16 100644
--- a/doc/development/gitaly.md
+++ b/doc/development/gitaly.md
@@ -235,7 +235,7 @@ changes to embed a new SHA in the `Gemfile.lock` file.
 
 ---
 
-[Return to Development documentation](README.md)
+[Return to Development documentation](index.md)
 
 ## Wrapping RPCs in Feature Flags
 
diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md
index ad24353fde8..dab25711a59 100644
--- a/doc/development/go_guide/index.md
+++ b/doc/development/go_guide/index.md
@@ -507,4 +507,4 @@ If the scanner report is small, less than 35 lines, then feel free to [inline th
 
 ---
 
-[Return to Development documentation](../README.md).
+[Return to Development documentation](../index.md).
diff --git a/doc/development/index.md b/doc/development/index.md
new file mode 100644
index 00000000000..bc996fdff21
--- /dev/null
+++ b/doc/development/index.md
@@ -0,0 +1,308 @@
+---
+comments: false
+type: index, dev
+stage: none
+group: Development
+info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
+description: "Development Guidelines: learn how to contribute to GitLab."
+---
+
+# Contributor and Development Docs
+
+Learn the processes and technical information needed for contributing to GitLab.
+
+This content is intended for members of the GitLab Team as well as community
+contributors. Content specific to the GitLab Team should instead be included in
+the [Handbook](https://about.gitlab.com/handbook/).
+
+For information on using GitLab to work on your own software projects, see the
+[GitLab user documentation](../user/index.md).
+
+For information on working with the GitLab APIs, see the [API documentation](../api/README.md).
+
+For information about how to install, configure, update, and upgrade your own
+GitLab instance, see the [administration documentation](../administration/index.md).
+
+## Get started
+
+- Set up the GitLab development environment with the
+  [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/README.md)
+- [GitLab contributing guide](contributing/index.md)
+  - [Issues workflow](contributing/issue_workflow.md) for more information about:
+    - Issue tracker guidelines.
+    - Triaging.
+    - Labels.
+    - Feature proposals.
+    - Issue weight.
+    - Regression issues.
+    - Technical or UX debt.
+  - [Merge requests workflow](contributing/merge_request_workflow.md) for more
+    information about:
+    - Merge request guidelines.
+    - Contribution acceptance criteria.
+    - Definition of done.
+    - Dependencies.
+  - [Style guides](contributing/style_guides.md)
+  - [Implement design & UI elements](contributing/design.md)
+- [GitLab Architecture Overview](architecture.md)
+- [Rake tasks](rake_tasks.md) for development
+
+## Processes
+
+**Must-reads:**
+
+- [Guide on adapting existing and introducing new components](architecture.md#adapting-existing-and-introducing-new-components)
+- [Code review guidelines](code_review.md) for reviewing code and having code
+  reviewed
+- [Database review guidelines](database_review.md) for reviewing
+  database-related changes and complex SQL queries, and having them reviewed
+- [Secure coding guidelines](secure_coding_guidelines.md)
+- [Pipelines for the GitLab project](pipelines.md)
+
+Complementary reads:
+
+- [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md)
+- [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer)
+- [Guidelines for implementing Enterprise Edition features](ee_features.md)
+- [Danger bot](dangerbot.md)
+- [Guidelines for changelogs](changelog.md)
+- [Requesting access to ChatOps on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLab team members)
+- [Patch release process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/patch/process.md#process-for-developers)
+- [Adding a new service component to GitLab](adding_service_component.md)
+
+### Development guidelines review
+
+When you submit a change to the GitLab development guidelines, who
+you ask for reviews depends on the level of change.
+
+#### Wording, style, or link changes
+
+Not all changes require extensive review. For example, MRs that don't change the
+content's meaning or function can be reviewed, approved, and merged by any
+maintainer or Technical Writer. These can include:
+
+- Typo fixes.
+- Clarifying links, such as to external programming language documentation.
+- Changes to comply with the [Documentation Style Guide](documentation/index.md)
+  that don't change the intent of the documentation page.
+
+#### Specific changes
+
+If the MR proposes changes that are limited to a particular stage, group, or team,
+request a review and approval from an experienced GitLab Team Member in that
+group. For example, if you're documenting a new internal API used exclusively by
+a given group, request an engineering review from one of the group's members.
+
+After the engineering review is complete, assign the MR to the
+[Technical Writer associated with the stage and group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)
+in the modified documentation page's metadata.
+
+If you have questions or need further input, request a review from the
+Technical Writer assigned to the [Development Guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines).
+
+#### Broader changes
+
+Some changes affect more than one group. For example:
+
+- Changes to [code review guidelines](code_review.md).
+- Changes to [commit message guidelines](contributing/merge_request_workflow.md#commit-messages-guidelines).
+- Changes to guidelines in [feature flags in development of GitLab](feature_flags/).
+- Changes to [feature flags documentation guidelines](documentation/feature_flags.md).
+
+In these cases, use the following workflow:
+
+1. Request a peer review from a member of your team.
+1. Request a review and approval of an Engineering Manager (EM)
+   or Staff Engineer who's responsible for the area in question:
+
+   - [Frontend](https://about.gitlab.com/handbook/engineering/frontend/)
+   - [Backend](https://about.gitlab.com/handbook/engineering/)
+   - [Database](https://about.gitlab.com/handbook/engineering/development/database/)
+   - [User Experience (UX)](https://about.gitlab.com/handbook/engineering/ux/)
+   - [Security](https://about.gitlab.com/handbook/engineering/security/)
+   - [Quality](https://about.gitlab.com/handbook/engineering/quality/)
+     - [Engineering Productivity](https://about.gitlab.com/handbook/engineering/quality/engineering-productivity-team/)
+   - [Infrastructure](https://about.gitlab.com/handbook/engineering/infrastructure/)
+   - [Technical Writing](https://about.gitlab.com/handbook/engineering/ux/technical-writing/)
+
+   You can skip this step for MRs authored by EMs or Staff Engineers responsible
+   for their area.
+
+   If there are several affected groups, you may need approvals at the
+   EM/Staff Engineer level from each affected area.
+
+1. After completing the reviews, consult with the EM/Staff Engineer
+   author / approver of the MR.
+
+   If this is a significant change across multiple areas, request final review
+   and approval from the VP of Development, the DRI for Development Guidelines,
+   @clefelhocz1.
+
+1. After all approvals are complete, assign the merge request to the
+   Technical Writer for [Development Guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines)
+   for final content review and merge. The Technical Writer may ask for
+   additional approvals as previously suggested before merging the MR.
+
+## UX and Frontend guides
+
+- [GitLab Design System](https://design.gitlab.com/), for building GitLab with
+  existing CSS styles and elements
+- [Frontend guidelines](fe_guide/index.md)
+- [Emoji guide](fe_guide/emojis.md)
+
+## Backend guides
+
+- [Directory structure](directory_structure.md)
+- [GitLab utilities](utilities.md)
+- [Issuable-like Rails models](issuable-like-models.md)
+- [Logging](logging.md)
+- [API style guide](api_styleguide.md) for contributing to the API
+- [GraphQL API style guide](api_graphql_styleguide.md) for contributing to the
+  [GraphQL API](../api/graphql/index.md)
+- [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers
+- [Working with Gitaly](gitaly.md)
+- [Manage feature flags](feature_flags/index.md)
+- [Licensed feature availability](licensed_feature_availability.md)
+- [Dealing with email/mailers](emails.md)
+- [Shell commands](shell_commands.md) in the GitLab codebase
+- [`Gemfile` guidelines](gemfile.md)
+- [Pry debugging](pry_debugging.md)
+- [Sidekiq debugging](../administration/troubleshooting/sidekiq.md)
+- [Accessing session data](session.md)
+- [Gotchas](gotchas.md) to avoid
+- [Avoid modules with instance variables](module_with_instance_variables.md), if
+  possible
+- [How to dump production data to staging](db_dump.md)
+- [Working with the GitHub importer](github_importer.md)
+- [Import/Export development documentation](import_export.md)
+- [Test Import Project](import_project.md)
+- [Group migration](bulk_import.md)
+- [Elasticsearch integration docs](elasticsearch.md)
+- [Working with Merge Request diffs](diffs.md)
+- [Kubernetes integration guidelines](kubernetes.md)
+- [Permissions](permissions.md)
+- [Guidelines for reusing abstractions](reusing_abstractions.md)
+- [DeclarativePolicy framework](policies.md)
+- [How Git object deduplication works in GitLab](git_object_deduplication.md)
+- [Geo development](geo.md)
+- [Routing](routing.md)
+- [Repository mirroring](repository_mirroring.md)
+- [Git LFS](lfs.md)
+- [Developing against interacting components or features](interacting_components.md)
+- [File uploads](uploads.md)
+- [Auto DevOps development guide](auto_devops.md)
+- [Mass Inserting Models](mass_insert.md)
+- [Value Stream Analytics development guide](value_stream_analytics.md)
+- [Issue types vs first-class types](issue_types.md)
+- [Application limits](application_limits.md)
+- [Redis guidelines](redis.md)
+- [Rails initializers](rails_initializers.md)
+- [Code comments](code_comments.md)
+- [Renaming features](renaming_features.md)
+- [Windows Development on GCP](windows.md)
+- [Code Intelligence](code_intelligence/index.md)
+- [Approval Rules](approval_rules.md)
+- [Feature categorization](feature_categorization/index.md)
+- [Wikis development guide](wikis.md)
+- [Newlines style guide](newlines_styleguide.md)
+- [Image scaling guide](image_scaling.md)
+- [Export to CSV](export_csv.md)
+- [Cascading Settings](cascading_settings.md)
+- [FIPS compliance](fips_compliance.md)
+
+## Performance guides
+
+- [Instrumentation](instrumentation.md) for Ruby code running in production
+  environments.
+- [Performance guidelines](performance.md) for writing code, benchmarks, and
+  certain patterns to avoid.
+- [Merge request performance guidelines](merge_request_performance_guidelines.md)
+  for ensuring merge requests do not negatively impact GitLab performance
+- [Profiling](profiling.md) a URL, measuring performance using Sherlock, or
+  tracking down N+1 queries using Bullet.
+- [Cached queries guidelines](cached_queries.md), for tracking down N+1 queries
+  masked by query caching, memory profiling and why should we avoid cached
+  queries.
+
+## Database guides
+
+See [database guidelines](database/index.md).
+
+## Integration guides
+
+- [Jira Connect app](integrations/jira_connect.md)
+- [Security Scanners](integrations/secure.md)
+- [Secure Partner Integration](integrations/secure_partner_integration.md)
+- [How to run Jenkins in development environment](integrations/jenkins.md)
+- [How to run local `Codesandbox` integration for Web IDE Live Preview](integrations/codesandbox.md)
+
+## Testing guides
+
+- [Testing standards and style guidelines](testing_guide/index.md)
+- [Frontend testing standards and style guidelines](testing_guide/frontend_testing.md)
+
+## Refactoring guides
+
+- [Refactoring guidelines](refactoring_guide/index.md)
+
+## Deprecation guides
+
+- [Deprecation guidelines](deprecation_guidelines/index.md)
+
+## Documentation guides
+
+- [Writing documentation](documentation/index.md)
+- [Documentation style guide](documentation/styleguide/index.md)
+- [Markdown](../user/markdown.md)
+
+## Internationalization (i18n) guides
+
+- [Introduction](i18n/index.md)
+- [Externalization](i18n/externalization.md)
+- [Translation](i18n/translation.md)
+
+## Product Intelligence guides
+
+- [Product Intelligence guide](https://about.gitlab.com/handbook/product/product-intelligence-guide/)
+- [Usage Ping guide](usage_ping/index.md)
+- [Snowplow guide](snowplow/index.md)
+
+## Experiment guide
+
+- [Introduction](experiment_guide/index.md)
+
+## Build guides
+
+- [Building a package for testing purposes](build_test_package.md)
+
+## Compliance
+
+- [Licensing](licensing.md) for ensuring license compliance
+
+## Go guides
+
+- [Go Guidelines](go_guide/index.md)
+
+## Shell Scripting guides
+
+- [Shell scripting standards and style guidelines](shell_scripting_guide/index.md)
+
+## Domain-specific guides
+
+- [CI/CD development documentation](cicd/index.md)
+- [AppSec development documentation](appsec/index.md)
+
+## Other Development guides
+
+- [Defining relations between files using projections](projections.md)
+- [Reference processing](reference_processing.md)
+- [Compatibility with multiple versions of the application running at the same time](multi_version_compatibility.md)
+- [Features inside `.gitlab/`](features_inside_dot_gitlab.md)
+- [Dashboards for stage groups](stage_group_dashboards.md)
+- [Preventing transient bugs](transient/prevention-patterns.md)
+
+## Other GitLab Development Kit (GDK) guides
+
+- [Run full Auto DevOps cycle in a GDK instance](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/auto_devops.md)
+- [Using GitLab Runner with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/runner.md)
+- [Using the Web IDE terminal with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/web_ide_terminal_gdk_setup.md)
diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md
index 872dea060cd..5dd586105e9 100644
--- a/doc/development/pipelines.md
+++ b/doc/development/pipelines.md
@@ -585,7 +585,7 @@ several reasons:
 - It significantly reduces load on the file server, as smaller deltas mean less time spent in `git pack-objects`.
 
 The pre-clone step works by using the `CI_PRE_CLONE_SCRIPT` variable
-[defined by GitLab.com shared runners](../ci/runners/README.md#pre-clone-script).
+[defined by GitLab.com shared runners](../ci/runners/index.md#pre-clone-script).
 
 The `CI_PRE_CLONE_SCRIPT` is currently defined as a project CI/CD variable:
 
@@ -813,4 +813,4 @@ and included in `rules` definitions via [YAML anchors](../ci/yaml/README.md#anch
 
 ---
 
-[Return to Development documentation](README.md)
+[Return to Development documentation](index.md)
diff --git a/doc/development/shell_scripting_guide/index.md b/doc/development/shell_scripting_guide/index.md
index 6071ae3a09d..d3b446d45da 100644
--- a/doc/development/shell_scripting_guide/index.md
+++ b/doc/development/shell_scripting_guide/index.md
@@ -127,4 +127,4 @@ for code review.
 
 ---
 
-[Return to Development documentation](../README.md).
+[Return to Development documentation](../index.md).
diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md
index c22a4e0b3ad..889dc45d6e3 100644
--- a/doc/development/testing_guide/index.md
+++ b/doc/development/testing_guide/index.md
@@ -70,4 +70,4 @@ Everything you should know about how to run end-to-end tests using
 
 Everything you should know about how to test migrations.
 
-[Return to Development documentation](../README.md)
+[Return to Development documentation](../index.md)