Add latest changes from gitlab-org/gitlab@master

5 files changed, 142 insertions, 2 deletions

diff --git a/doc/development/avoiding_required_stops.md b/doc/development/avoiding_required_stops.md
new file mode 100644
index 00000000000..0308e0c30c0
--- /dev/null
+++ b/doc/development/avoiding_required_stops.md
@@ -0,0 +1,137 @@
+---
+stage: Systems
+group: Distribution
+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
+---
+
+# Avoiding required stops
+
+Required stops are any changes to GitLab [components](architecture.md) or
+dependencies that result in the need to upgrade to and stop at a specific
+`major.minor` version when [upgrading GitLab](../update/index.md).
+
+While Development maintains a [maintainenance policy](../policy/maintenance.md)
+that results in a three-release (3 month) backport window - GitLab maintains a
+much longer window of [version support](https://about.gitlab.com/support/statement-of-support/#version-support)
+that includes the current major version, as well as the two previous major
+versions. Based on the schedule of previous major releases, GitLab customers can
+lag behind the current release for up to three years and still expect to have
+support for upgrades.
+
+For example, a GitLab user upgrading from GitLab 14.0.12 to GitLab 16.1,
+which is a fully supported [upgrade path](../update/index.md#upgrade-paths), may have
+the following required stops: `14.3.6`, `14.9.5`, `14.10.5`, `15.0.5`, `15.1.6`,
+`15.4.6`, and `15.11.11` before upgrading to the latest `16.1.z` version.
+
+Past required stops have not been discovered for months after their introduction,
+often as the result of extensive troubleshooting and assistance from Support
+Engineers, Customer Success Managers, and Development Engineers as users upgrade
+across greater than 1-3 minor releases.
+
+Wherever possible, a required stop should be avoided. If it can't be avoided,
+the required stop should be aligned to a _scheduled_ required stop.
+
+Scheduled required stops are often implemented for the previous `major`.`minor`
+release just prior to a `major` version release in order to accomodate multiple
+[planned deprecations](../update/terminology.md#deprecation) and known
+[breaking changes](../update/terminology.md#breaking-change).
+
+Additionally, as of GitLab 16, we have introduced
+[_scheduled_ `major`.`minor` required stops](../update/index.md#upgrade-paths):
+
+>>>
+During GitLab 16.x, we are scheduling two or three required upgrade stops.
+
+We will give at least two milestones of notice when we schedule a required
+upgrade stop. The first planned required upgrade stop is scheduled for GitLab
+16.3. If nothing is introduced requiring an upgrade stop, GitLab 16.3 will be
+treated as a regular upgrade.
+>>>
+
+## Causes of required stops
+
+### Inaccurate assumptions about completed migrations
+
+The majority of required stops are due to assumptions about the state of the
+data model in a given release, usually in the form of interdependent database
+migrations, or code changes that assume that schema changes introduced in
+prior migrations have completed by the time the code loads.
+
+Designing changes and migrations for [backwards compatibility between versions](multi_version_compatibility.md) can mitigate stop concerns with continuous or
+"zero-downtime" upgrades. However, the **contract** phase will likely introduce
+a required stop when a migration/code change is introduced that requires
+that background migrations have completed before running or loading.
+
+WARNING:
+If you're considering adding or removing a migration, or introducing code that
+assumes that migrations have completed in a given release, first review
+the database-related documentation on [required stops](database/required_stops.md).
+
+#### Examples
+
+- GitLab `12.1`: Introduced a background migration changing `merge_status` in
+  MergeRequests depending on the `state` value. The `state` attribute was removed
+  in `12.10`. It took until `13.6` to document the required stop.
+- GitLab `13.8`: Includes a background migration to deal with duplicate service
+  records. In `13.9`, a unique index was applied in another migration that
+  depended on the background migration completing. Not discovered/documented until
+  GitLab `14.3`
+- GitLab `14.3`: Includes a potentially long-running background migration against
+  `merge_request_diff_commits` that was foregrounded in `14.5`. This change resulted in
+   extensive downtime for users with large GitLab installations. Not documented
+   until GitLab `15.1`
+- GitLab `14.9`: Includes a batched background migration for `namespaces` and `projects`
+  that needs to finish before another batched background migration added in `14.10` executes,
+  forcing a required stop. The migration can take hours or days to complete on
+  large GitLab installations.
+
+Additional details as well as links to related issues and merge requests can be
+found in: [Issue: Put in place measures to avoid addition/proliferation of GitLab upgrade path stops](https://gitlab.com/gitlab-org/gitlab/-/issues/375553)
+
+### Removal of code workarounds and mitigations
+
+Similar to assumptions about the data model/schema/migration state, required
+`major.minor` stops have been introduced due to the intentional removal of
+code implemented to workaround previously discovered issues.
+
+#### Examples
+
+- GitLab `13.1`: A security fix in Rails `6.0.3.1` introduced a CSRF token change
+  (causing a canary environment incident). We introduced code to maintain acceptance
+  of previously generated tokens, and removed the code in `13.2`, creating a known
+  required stop in `13.1`.
+- GitLab `15.4`: Introduces a migration to fix an inaccurate `expires_at` timestamp
+  for job artifacts that had been mitigated in code since GitLab `14.9`. The
+  workaround was removed in GitLab `15.6`, causing `15.4` to be a required stop.
+
+### Deprecations
+
+Deprecations, particularly [breaking changes](../update/terminology.md#breaking-change)
+can also cause required stops if they introduce long migration delays or require
+manual actions on the part of GitLab administrators.
+
+These are generally accepted as a required stop around a major release, either
+stopping at the latest `major.minor` release immediately proceeding
+a new `major` release, and potentially the lastest `major.0` patch release, and
+to date, discovered required stops related to deprecations have been limited to
+these releases.
+
+#### Examples
+
+Examples of deprecations are too numerous to be listed here, but can found
+in the [deprecations and removals by version](../update/deprecations.md) as well
+as the [version-specific upgrading instructions](../update/index.md#version-specific-upgrading-instructions),
+[version-specific changes for the GitLab package (Omnibus)](../update/package/index.md#version-specific-changes),
+and [GitLab chart upgrade notes](https://docs.gitlab.com/charts/installation/upgrade.html).
+
+## Further reading
+
+- [Documentation: Database - Adding required stops](database/required_stops.md)
+- [Documentation: Upgrading GitLab](../update/index.md)
+  - [Package (Omnibus) upgrade](../update/package/index.md)
+  - [Docker upgrade](../install/docker.md#upgrade)
+  - [GitLab chart](https://docs.gitlab.com/charts/installation/upgrade.html)
+- [Issue: Put in place measures to avoid addition/proliferation of GitLab upgrade path stops](https://gitlab.com/gitlab-org/gitlab/-/issues/375553)
+- [Issue: Brainstorm ways for background migrations to be finalized without introducing a required upgrade step](https://gitlab.com/gitlab-org/gitlab/-/issues/357561)
+- [Issue: Scheduled required paths for GitLab upgrades to improve UX](https://gitlab.com/gitlab-org/gitlab/-/issues/358417)
+- [Epic: GitLab Releases and Maintenance policies](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/988)
diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index 95d2c8c66bb..6aedb18c15d 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -400,6 +400,8 @@ Maintainers are the DRI of assuring that the acceptance criteria of a merge requ
 In general, [quality is everyone's responsibility](https://about.gitlab.com/handbook/engineering/quality/),
 but maintainers of an MR are held responsible for **ensuring** that an MR meets those general quality standards.
 
+This includes [avoiding the creation of technical debt in follow-up issues](contributing/issue_workflow.md#technical-debt-in-follow-up-issues).
+
 If a maintainer feels that an MR is substantial enough, or requires a [domain expert](#domain-experts),
 maintainers have the discretion to request a review from another reviewer, or maintainer. Here are some
 examples of maintainers proactively doing this during review:
diff --git a/doc/development/development_processes.md b/doc/development/development_processes.md
index c5d60d18419..4ce9df8d7da 100644
--- a/doc/development/development_processes.md
+++ b/doc/development/development_processes.md
@@ -22,6 +22,7 @@ Must-reads:
 
 Complementary reads:
 
+- [Avoiding required stops](avoiding_required_stops.md)
 - [Contribute to GitLab](contributing/index.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)
 - [Patch release process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/patch/process.md#process-for-developers)
diff --git a/doc/development/internal_analytics/service_ping/index.md b/doc/development/internal_analytics/service_ping/index.md
index 69d37f0dae2..22e66a247c9 100644
--- a/doc/development/internal_analytics/service_ping/index.md
+++ b/doc/development/internal_analytics/service_ping/index.md
@@ -22,7 +22,7 @@ and sales teams understand how GitLab is used. The data helps to:
 Service Ping information is not anonymous. It's linked to the instance's hostname, but does
 not contain project names, usernames, or any other specific data.
 
-Service Ping is enabled by default. However, you can [disable](../../../user/admin_area/settings/usage_statistics.md#enable-or-disable-usage-statistics) it on any self-managed instance. When Service Ping is enabled, GitLab gathers data from the other instances and can show your instance's usage statistics to your users.
+Service Ping is enabled by default. However, you can [disable](../../../administration/settings/usage_statistics.md#enable-or-disable-usage-statistics) it on any self-managed instance. When Service Ping is enabled, GitLab gathers data from the other instances and can show your instance's usage statistics to your users.
 
 ## Service Ping terminology
 
diff --git a/doc/development/internal_analytics/service_ping/metrics_dictionary.md b/doc/development/internal_analytics/service_ping/metrics_dictionary.md
index 7b7468740dc..90a99d1ec56 100644
--- a/doc/development/internal_analytics/service_ping/metrics_dictionary.md
+++ b/doc/development/internal_analytics/service_ping/metrics_dictionary.md
@@ -150,7 +150,7 @@ For more information about the aggregation type of each feature, see the [`commo
 We use the following categories to classify a metric:
 
 - `operational`: Required data for operational purposes.
-- `optional`: Default value for a metric. Data that is optional to collect. This can be [enabled or disabled](../../../user/admin_area/settings/usage_statistics.md#enable-or-disable-usage-statistics) in the Admin Area.
+- `optional`: Default value for a metric. Data that is optional to collect. This can be [enabled or disabled](../../../administration/settings/usage_statistics.md#enable-or-disable-usage-statistics) in the Admin Area.
 - `subscription`: Data related to licensing.
 - `standard`: Standard set of identifiers that are included when collecting data.