Add latest changes from gitlab-org/gitlab@master

10 files changed, 25 insertions, 32 deletions

diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md
index edf159a116a..b64d25ccf64 100644
--- a/doc/development/application_limits.md
+++ b/doc/development/application_limits.md
@@ -38,7 +38,7 @@ It's recommended to create two separate migration script files.
    desired limit using `create_or_update_plan_limit` migration helper, such as:
 
    ```ruby
-   class InsertProjectHooksPlanLimits < Gitlab::Database::Migration[1.0]
+   class InsertProjectHooksPlanLimits < Gitlab::Database::Migration[2.0]
      def up
        create_or_update_plan_limit('project_hooks', 'default', 0)
        create_or_update_plan_limit('project_hooks', 'free', 10)
diff --git a/doc/development/cascading_settings.md b/doc/development/cascading_settings.md
index 22f146c3f5a..1a0f0ec5b5f 100644
--- a/doc/development/cascading_settings.md
+++ b/doc/development/cascading_settings.md
@@ -38,7 +38,7 @@ Settings are not cascading by default. To define a cascading setting, take the f
    `application_settings`.
 
     ```ruby
-    class AddDelayedProjectRemovalCascadingSetting < Gitlab::Database::Migration[1.0]
+    class AddDelayedProjectRemovalCascadingSetting < Gitlab::Database::Migration[2.0]
       include Gitlab::Database::MigrationHelpers::CascadingNamespaceSettings
 
       enable_lock_retries!
diff --git a/doc/development/database/background_migrations.md b/doc/development/database/background_migrations.md
index 8e6f29b9eb8..fe62bbc6b14 100644
--- a/doc/development/database/background_migrations.md
+++ b/doc/development/database/background_migrations.md
@@ -236,7 +236,7 @@ Next we need a post-deployment migration that schedules the migration for
 existing data.
 
 ```ruby
-class ScheduleExtractIntegrationsUrl < Gitlab::Database::Migration[1.0]
+class ScheduleExtractIntegrationsUrl < Gitlab::Database::Migration[2.0]
   disable_ddl_transaction!
 
   MIGRATION = 'ExtractIntegrationsUrl'
@@ -263,7 +263,7 @@ jobs and manually run on any un-migrated rows. Such a migration would look like
 this:
 
 ```ruby
-class ConsumeRemainingExtractIntegrationsUrlJobs < Gitlab::Database::Migration[1.0]
+class ConsumeRemainingExtractIntegrationsUrlJobs < Gitlab::Database::Migration[2.0]
   disable_ddl_transaction!
 
   def up
diff --git a/doc/development/database/loose_foreign_keys.md b/doc/development/database/loose_foreign_keys.md
index abf66368548..962cd2602bc 100644
--- a/doc/development/database/loose_foreign_keys.md
+++ b/doc/development/database/loose_foreign_keys.md
@@ -192,7 +192,7 @@ trigger needs to be configured only once. If the model already has at least one
 `loose_foreign_key` definition, then this step can be skipped:
 
 ```ruby
-class TrackProjectRecordChanges < Gitlab::Database::Migration[1.0]
+class TrackProjectRecordChanges < Gitlab::Database::Migration[2.0]
   include Gitlab::Database::MigrationHelpers::LooseForeignKeyHelpers
 
   enable_lock_retries!
@@ -227,7 +227,7 @@ trigger. If the foreign key is deleted earlier, there is a good chance of
 introducing data inconsistency which needs manual cleanup:
 
 ```ruby
-class RemoveProjectsCiPipelineFk < Gitlab::Database::Migration[1.0]
+class RemoveProjectsCiPipelineFk < Gitlab::Database::Migration[2.0]
   disable_ddl_transaction!
 
   def up
@@ -258,7 +258,7 @@ records in the database.
 Migration for removing the trigger:
 
 ```ruby
-class UnTrackProjectRecordChanges < Gitlab::Database::Migration[1.0]
+class UnTrackProjectRecordChanges < Gitlab::Database::Migration[2.0]
   include Gitlab::Database::MigrationHelpers::LooseForeignKeyHelpers
 
   enable_lock_retries!
@@ -278,7 +278,7 @@ table however, there is still a chance for having leftover pending records in th
 must be removed with an inline data migration.
 
 ```ruby
-class RemoveLeftoverProjectDeletions < Gitlab::Database::Migration[1.0]
+class RemoveLeftoverProjectDeletions < Gitlab::Database::Migration[2.0]
   disable_ddl_transaction!
 
   def up
diff --git a/doc/development/database/not_null_constraints.md b/doc/development/database/not_null_constraints.md
index dccaff2df00..53ab9a83d60 100644
--- a/doc/development/database/not_null_constraints.md
+++ b/doc/development/database/not_null_constraints.md
@@ -25,7 +25,7 @@ For example, consider a migration that creates a table with two `NOT NULL` colum
 `db/migrate/20200401000001_create_db_guides.rb`:
 
 ```ruby
-class CreateDbGuides < Gitlab::Database::Migration[1.0]
+class CreateDbGuides < Gitlab::Database::Migration[2.0]
   def change
     create_table :db_guides do |t|
       t.bigint :stars, default: 0, null: false
@@ -44,7 +44,7 @@ For example, consider a migration that adds a new `NOT NULL` column `active` to
 `db/migrate/20200501000001_add_active_to_db_guides.rb`:
 
 ```ruby
-class AddExtendedTitleToSprints < Gitlab::Database::Migration[1.0]
+class AddExtendedTitleToSprints < Gitlab::Database::Migration[2.0]
   def change
     add_column :db_guides, :active, :boolean, default: true, null: false
   end
@@ -116,7 +116,7 @@ with `validate: false` in a post-deployment migration,
 `db/post_migrate/20200501000001_add_not_null_constraint_to_epics_description.rb`:
 
 ```ruby
-class AddNotNullConstraintToEpicsDescription < Gitlab::Database::Migration[1.0]
+class AddNotNullConstraintToEpicsDescription < Gitlab::Database::Migration[2.0]
   disable_ddl_transaction!
 
   def up
@@ -147,7 +147,7 @@ so we add a post-deployment migration for the 13.0 milestone (current),
 `db/post_migrate/20200501000002_cleanup_epics_with_null_description.rb`:
 
 ```ruby
-class CleanupEpicsWithNullDescription < Gitlab::Database::Migration[1.0]
+class CleanupEpicsWithNullDescription < Gitlab::Database::Migration[2.0]
   # With BATCH_SIZE=1000 and epics.count=29500 on GitLab.com
   # - 30 iterations will be run
   # - each requires on average ~150ms
@@ -185,7 +185,7 @@ migration helper in a final post-deployment migration,
 `db/post_migrate/20200601000001_validate_not_null_constraint_on_epics_description.rb`:
 
 ```ruby
-class ValidateNotNullConstraintOnEpicsDescription < Gitlab::Database::Migration[1.0]
+class ValidateNotNullConstraintOnEpicsDescription < Gitlab::Database::Migration[2.0]
   disable_ddl_transaction!
 
   def up
diff --git a/doc/development/database/single_table_inheritance.md b/doc/development/database/single_table_inheritance.md
index ad0101e1594..32de1fdea35 100644
--- a/doc/development/database/single_table_inheritance.md
+++ b/doc/development/database/single_table_inheritance.md
@@ -47,7 +47,7 @@ This ensures that the migration loads the columns for the migration in isolation
 and the helper disables STI by default.
 
 ```ruby
-class EnqueueSomeBackgroundMigration < Gitlab::Database::Migration[1.0]
+class EnqueueSomeBackgroundMigration < Gitlab::Database::Migration[2.0]
   disable_ddl_transaction!
 
   def up
diff --git a/doc/development/database/table_partitioning.md b/doc/development/database/table_partitioning.md
index bf12329473d..24a7cbe0f87 100644
--- a/doc/development/database/table_partitioning.md
+++ b/doc/development/database/table_partitioning.md
@@ -173,7 +173,7 @@ An example migration of partitioning the `audit_events` table by its
 `created_at` column would look like:
 
 ```ruby
-class PartitionAuditEvents < Gitlab::Database::Migration[1.0]
+class PartitionAuditEvents < Gitlab::Database::Migration[2.0]
   include Gitlab::Database::PartitioningMigrationHelpers
 
   def up
@@ -200,7 +200,7 @@ into the partitioned copy.
 Continuing the above example, the migration would look like:
 
 ```ruby
-class BackfillPartitionAuditEvents < Gitlab::Database::Migration[1.0]
+class BackfillPartitionAuditEvents < Gitlab::Database::Migration[2.0]
   include Gitlab::Database::PartitioningMigrationHelpers
 
   def up
@@ -233,7 +233,7 @@ failed jobs.
 Once again, continuing the example, this migration would look like:
 
 ```ruby
-class CleanupPartitionedAuditEventsBackfill < Gitlab::Database::Migration[1.0]
+class CleanupPartitionedAuditEventsBackfill < Gitlab::Database::Migration[2.0]
   include Gitlab::Database::PartitioningMigrationHelpers
 
   def up
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md
index 65ad8dea688..ce9fd671a39 100644
--- a/doc/development/documentation/styleguide/word_list.md
+++ b/doc/development/documentation/styleguide/word_list.md
@@ -720,25 +720,18 @@ Do not use **navigate**. Use **go** instead. For example:
 
 ## need to, should
 
-Try to avoid **needs to**, because it's wordy. Avoid **should** when you can be more specific. If something is required, use **must**.
+Try to avoid **needs to**, because it's wordy. If something is recommended, use **should** instead. If something is required, use **must**.
 
 Use:
 
-- You must set the variable.
-- Set the variable.
+- You should set the variable. (recommended)
+- You must set the variable. (required)
+- Set the variable. (required)
 
 Instead of:
 
 - You need to set the variable.
 
-**Should** is acceptable for recommended actions or items, or in cases where an event may not
-happen. For example:
-
-- Although you can configure the installation manually, you should use the express configuration to
-  avoid complications.
-- You should see a success message in the console. Contact support if an error message appears
-  instead.
-
 ## note that
 
 Do not use **note that** because it's wordy.
@@ -1173,7 +1166,7 @@ Instead of:
 
 - We created a feature for you to add widgets.
 
-One exception: You can use **we recommend** instead of **it is recommended** or **GitLab recommends**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml))
+([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml))
 
 ## whitelist
 
diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md
index c2caa354567..d3d809c5386 100644
--- a/doc/development/prometheus_metrics.md
+++ b/doc/development/prometheus_metrics.md
@@ -36,7 +36,7 @@ After you add or change an existing common metric, you must [re-run the import s
 Or, you can create a database migration:
 
 ```ruby
-class ImportCommonMetrics < Gitlab::Database::Migration[1.0]
+class ImportCommonMetrics < Gitlab::Database::Migration[2.0]
   def up
     ::Gitlab::DatabaseImporters::CommonMetrics::Importer.new.execute
   end
diff --git a/doc/development/sql.md b/doc/development/sql.md
index 5829d27b8ee..cdc952eb08b 100644
--- a/doc/development/sql.md
+++ b/doc/development/sql.md
@@ -103,7 +103,7 @@ transaction. Transactions for migrations can be disabled using the following
 pattern:
 
 ```ruby
-class MigrationName < Gitlab::Database::Migration[1.0]
+class MigrationName < Gitlab::Database::Migration[2.0]
   disable_ddl_transaction!
 end
 ```
@@ -111,7 +111,7 @@ end
 For example:
 
 ```ruby
-class AddUsersLowerUsernameEmailIndexes < Gitlab::Database::Migration[1.0]
+class AddUsersLowerUsernameEmailIndexes < Gitlab::Database::Migration[2.0]
   disable_ddl_transaction!
 
   def up