Add latest changes from gitlab-org/gitlab@14-2-stable-eev14.2.0-rc42

6 files changed, 85 insertions, 108 deletions

diff --git a/doc/update/img/batched_background_migrations_queued_v14_0.png b/doc/update/img/batched_background_migrations_queued_v14_0.png
new file mode 100644
index 00000000000..0b0792b5e7a
--- /dev/null
+++ b/doc/update/img/batched_background_migrations_queued_v14_0.png
diff --git a/doc/update/index.md b/doc/update/index.md
index 7875510167e..1289614c181 100644
--- a/doc/update/index.md
+++ b/doc/update/index.md
@@ -72,47 +72,33 @@ from the chart version to GitLab version to determine the [upgrade path](#upgrad
 
 ## Checking for background migrations before upgrading
 
-Certain major/minor releases may require a set of background migrations to be
-finished. The number of remaining migrations jobs can be found by running the
-following command:
+Certain major/minor releases may require different migrations to be
+finished before you update to the newer version.
+
+**For GitLab 14.0 and newer**
+
+To check the status of [batched background migrations](../user/admin_area/monitoring/background_migrations.md):
+
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the left sidebar, select **Monitoring > Background Migrations**.
+
+   ![queued batched background migrations table](img/batched_background_migrations_queued_v14_0.png)
 
 **For Omnibus installations**
 
-If using GitLab 12.9 and newer, run:
+You can also run:
 
 ```shell
 sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
 ```
 
-If using GitLab 12.8 and older, run the following using a [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session):
-
-```ruby
-puts Sidekiq::Queue.new("background_migration").size
-Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }.size
-```
-
 **For installations from source**
 
-If using GitLab 12.9 and newer, run:
-
 ```shell
 cd /home/git/gitlab
 sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
 ```
 
-If using GitLab 12.8 and older, run the following using a [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session):
-
-```ruby
-Sidekiq::Queue.new("background_migration").size
-Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }.size
-```
-
-### Batched background migrations
-
-Batched background migrations need to finish before you update to a newer version.
-
-Read more about [batched background migrations](../user/admin_area/monitoring/background_migrations.md).
-
 ### What do I do if my background migrations are stuck?
 
 WARNING:
@@ -201,15 +187,15 @@ accordingly, while also consulting the
 The following table, while not exhaustive, shows some examples of the supported
 upgrade paths.
 
-| Target version | Your version | Supported upgrade path | Note |
-| --------------------- | ------------ | ------------------------ | ---- |
-| `14.1.0`                | `13.9.2`      | `13.9.2` -> `13.12.6` -> `14.0.5` -> `14.1.0` | Two intermediate versions are required: `13.12` and `14.0`, then `14.1`. |
-| `13.5.4`                | `12.9.2`      | `12.9.2` -> `12.10.14` -> `13.0.14`  -> `13.1.11` -> `13.5.4` | Three intermediate versions are required: `12.10`, `13.0` and `13.1`, then `13.5.4`. |
-| `13.2.10`                | `11.5.0`      | `11.5.0` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.2.10` | Six intermediate versions are required: `11.11`, `12.0`, `12.1`, `12.10`, `13.0` and `13.1`, then `13.2.10`. |
-| `12.10.14`             | `11.3.4`       | `11.3.4` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14`             |  Three intermediate versions are required: `11.11`, `12.0` and `12.1`, then `12.10.14`. |
-| `12.9.5`             | `10.4.5`       | `10.4.5` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.9.5`   | Four intermediate versions are required: `10.8`, `11.11`, `12.0` and `12.1`, then `12.9.5`. |
-| `12.2.5`              | `9.2.6`        | `9.2.6` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.2.5` | Five intermediate versions are required: `9.5`, `10.8`, `11.11`, `12.0`, `12.1`, then `12.2.5`. |
-| `11.3.4`              | `8.13.4`       | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version 8, `9.5.10` is the last version in version 9, `10.8.7` is the last version in version 10. |
+| Target version | Your version | Supported upgrade path                                                                               | Note                                                                                                                              |
+| -------------- | ------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `14.1.2`       | `13.9.2`     | `13.9.2` -> `13.12.9` -> `14.0.7` -> `14.1.2`                                                        | Two intermediate versions are required: `13.12` and `14.0`, then `14.1`.                                                          |
+| `13.5.4`       | `12.9.2`     | `12.9.2` -> `12.10.14` -> `13.0.14`  -> `13.1.11` -> `13.5.4`                                        | Three intermediate versions are required: `12.10`, `13.0` and `13.1`, then `13.5.4`.                                              |
+| `13.2.10`      | `11.5.0`     | `11.5.0` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.2.10` | Six intermediate versions are required: `11.11`, `12.0`, `12.1`, `12.10`, `13.0` and `13.1`, then `13.2.10`.                      |
+| `12.10.14`     | `11.3.4`     | `11.3.4` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14`                                        | Three intermediate versions are required: `11.11`, `12.0` and `12.1`, then `12.10.14`.                                            |
+| `12.9.5`       | `10.4.5`     | `10.4.5` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.9.5`                              | Four intermediate versions are required: `10.8`, `11.11`, `12.0` and `12.1`, then `12.9.5`.                                       |
+| `12.2.5`       | `9.2.6`      | `9.2.6` -> `9.5.10` -> `10.8.7` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.2.5`                   | Five intermediate versions are required: `9.5`, `10.8`, `11.11`, `12.0`, `12.1`, then `12.2.5`.                                   |
+| `11.3.4`       | `8.13.4`     | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4`                                             | `8.17.7` is the last version in version 8, `9.5.10` is the last version in version 9, `10.8.7` is the last version in version 10. |
 
 ## Upgrading to a new major version
 
@@ -220,7 +206,7 @@ cannot guarantee that upgrading between major versions will be seamless.
 
 It is required to follow the following upgrade steps to ensure a successful *major* version upgrade:
 
-1. Upgrade to the latest minor version of the preceeding major version.
+1. Upgrade to the latest minor version of the preceding major version.
 1. Upgrade to the first minor version (`X.0.Z`) of the target major version.
 1. Proceed with upgrading to a newer release.
 
@@ -271,9 +257,10 @@ migrating data. Background migrations are only added in the monthly releases.
 Certain major/minor releases may require a set of background migrations to be
 finished. To guarantee this, such a release processes any remaining jobs
 before continuing the upgrading procedure. While this doesn't require downtime
-(if the above conditions are met) we recommend users to keep at least 1 week
-between upgrading major/minor releases, allowing the background migrations to
-finish. The time necessary to complete these migrations can be reduced by
+(if the above conditions are met) we require that you [wait for background
+migrations to complete](#checking-for-background-migrations-before-upgrading)
+between each major/minor release upgrade.
+The time necessary to complete these migrations can be reduced by
 increasing the number of Sidekiq workers that can process jobs in the
 `background_migration` queue. To see the size of this queue,
 [Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading).
@@ -376,7 +363,7 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap
 - Due to an issue where `BatchedBackgroundMigrationWorkers` were
   [not working](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/2785#note_614738345)
   for self-managed instances, a [fix was created](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65106)
-  and a [14.0.Z](#1400) version was released. If you haven't udpated to 14.0.Z, you need
+  and a [14.0.Z](#1400) version was released. If you haven't updated to 14.0.Z, you need
   to update to at least 14.1.0 that contains the same fix before you update to
   a later version.
 
diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md
index 92337f279d6..40dc57c554b 100644
--- a/doc/update/mysql_to_postgresql.md
+++ b/doc/update/mysql_to_postgresql.md
@@ -52,7 +52,7 @@ For other distributions, follow the instructions in PostgreSQL's
 and then install `pgloader`.
 
 If you are migrating to a Docker based installation, you must install
-pgLoader within the container as it is not included in the container image.
+pgLoader in the container as it is not included in the container image.
 
 1. Start a shell session in the context of the running container:
 
@@ -70,7 +70,7 @@ pgLoader within the container as it is not included in the container image.
 ## Omnibus GitLab installations
 
 For [Omnibus GitLab packages](https://about.gitlab.com/install/), you first
-need to enable the bundled PostgreSQL:
+enable the bundled PostgreSQL:
 
 1. Stop GitLab:
 
@@ -283,7 +283,7 @@ Sometimes, you might encounter some errors during or after the migration.
 
 ### Database error permission denied
 
-The PostgreSQL user that you use for the migration MUST have **superuser** privileges.
+The PostgreSQL user that you use for the migration **must** have **superuser** privileges.
 Otherwise, you may see a similar message to the following:
 
 ```plaintext
@@ -295,7 +295,7 @@ debugger invoked on a CL-POSTGRES-ERROR:INSUFFICIENT-PRIVILEGE in thread
     QUERY: ALTER TABLE approver_groups DISABLE TRIGGER ALL;
 ```
 
-### Experiencing 500 errors after the migration
+### 500 errors after the migration
 
 If you experience 500 errors after the migration, try to clear the cache:
 
diff --git a/doc/update/restore_after_failure.md b/doc/update/restore_after_failure.md
index e9c2c69ecb9..b8cceb8c367 100644
--- a/doc/update/restore_after_failure.md
+++ b/doc/update/restore_after_failure.md
@@ -13,7 +13,7 @@ However, it's important to know how to recover when problems do arise.
 
 In some cases after a failed upgrade, the fastest solution is to roll back to
 the previous version you were using. We recommend this path because the failed
-upgrade will likely have made database changes that can not be readily reverted.
+upgrade might have made database changes that cannot be readily reverted.
 
 First, roll back the code or package. For source installations this involves
 checking out the older version (branch or tag). For Omnibus installations this
@@ -33,7 +33,7 @@ older backup it can lead to migration failures on future upgrades.
 
 Starting in GitLab 8.6 we drop all tables prior to importing the backup to
 prevent this problem. If you've restored a backup to a version prior to 8.6 you
-may need to manually correct the problem next time you upgrade.
+may have to manually correct the problem next time you upgrade.
 
 Example error:
 
@@ -49,8 +49,8 @@ PG::DuplicateTable: ERROR:  relation "lfs_objects" already exists
 Copy the version from the error. In this case the version number is
 `20151103134857`.
 
->**WARNING:** Use the following steps only if you are certain this is what you
-need to do.
+WARNING:
+Use the following steps only if you are certain you must do them.
 
 ### GitLab 8.6+
 
@@ -65,9 +65,8 @@ sudo -u git -H bundle exec rake gitlab:db:mark_migration_complete[20151103134857
 sudo gitlab-rake gitlab:db:mark_migration_complete[20151103134857]
 ```
 
-Once the migration is successfully marked, run the Rake `db:migrate` task again.
-You might need to repeat this process several times until all failed
-migrations are marked complete.
+After the migration is successfully marked, run the Rake `db:migrate` task again.
+Repeat this process until all failed migrations are complete.
 
 ### GitLab < 8.6
 
@@ -86,6 +85,5 @@ ActiveRecord::Base.connection.execute("INSERT INTO schema_migrations (version) V
 exit
 ```
 
-Once the migration is successfully marked, run the Rake `db:migrate` task again.
-You might need to repeat this process several times until all failed
-migrations are marked complete.
+After the migration is successfully marked, run the Rake `db:migrate` task again.
+Repeat this process until all failed migrations are complete.
diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md
index 39e25fc11e7..dd7ef27feca 100644
--- a/doc/update/upgrading_from_source.md
+++ b/doc/update/upgrading_from_source.md
@@ -12,12 +12,10 @@ Users wishing to upgrade to 12.0.0 must take some extra steps. See the
 version specific upgrade instructions for 12.0.0 for more details.
 
 Make sure you view this update guide from the branch (version) of GitLab you
-would like to install (e.g., `11.8`. You can select the version in the version
-dropdown at the top left corner of GitLab (below the menu bar).
+would like to install (for example, `11.8`). You can select the required version of documentation in the dropdown at the top right corner of GitLab documentation page.
 
-In all examples, replace `BRANCH` with the branch for the version you upgrading
-to (e.g. `11-8-stable` for `11.8`), and replace `PREVIOUS_BRANCH` with the
-branch for the version you are upgrading from (e.g. `11-7-stable` for `11.7`).
+In each of the following examples, replace `BRANCH` with the branch of the version you upgrading to (for example, `11-8-stable` for `11.8`). Replace `PREVIOUS_BRANCH` with the
+branch for the version you are upgrading from (for example, `11-7-stable` for `11.7`).
 
 If the highest number stable branch is unclear please check the
 [GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation
@@ -29,7 +27,7 @@ the [Upgrading from CE to EE](upgrading_from_ce_to_ee.md) documentation.
 ## Upgrading to a new major version
 
 Major versions are reserved for backwards incompatible changes. We recommend that
-you first upgrade to the latest available minor version within your major version.
+you first upgrade to the latest available minor version of your current major version.
 Please follow the [Upgrade Recommendations](../policy/maintenance.md#upgrade-recommendations)
 to identify the ideal upgrade path.
 
@@ -152,7 +150,7 @@ WARNING:
 From GitLab 14.0, you must use at least PostgreSQL 12.
 
 The latest version of GitLab might depend on a more recent PostgreSQL version
-than what you're currently running. You may also need to enable some
+than what you are running. You may also have to enable some
 extensions. For more information, see the
 [PostgreSQL requirements](../install/requirements.md#postgresql-requirements)
 
@@ -212,9 +210,9 @@ git diff origin/PREVIOUS_BRANCH:lib/support/nginx/gitlab-ssl origin/BRANCH:lib/s
 git diff origin/PREVIOUS_BRANCH:lib/support/nginx/gitlab origin/BRANCH:lib/support/nginx/gitlab
 ```
 
-If you are using Strict-Transport-Security in your installation to continue
-using it you must enable it in your NGINX configuration as GitLab application no
-longer handles setting it.
+If you are using Strict-Transport-Security in your installation, you must enable it in your
+NGINX configuration to continue using it. This is because the GitLab application no longer
+sets it.
 
 If you are using Apache instead of NGINX see the updated [Apache templates](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache).
 Also note that because Apache does not support upstreams behind Unix sockets you
@@ -391,11 +389,11 @@ cp config/initializers/rack_attack.rb config/initializers/rack_attack_backup.rb
 
 ### 1. Revert the code to the previous version
 
-To revert to a previous version, you need to follow the upgrading guides
+To revert to a previous version, you must follow the upgrading guides
 for the previous version.
 
 For example, if you have upgraded to GitLab 12.6 and want to revert back to
-12.5, you need to follow the guides for upgrading from 12.4 to 12.5. You can
+12.5, follow the guides for upgrading from 12.4 to 12.5. You can
 use the version dropdown at the top of the page to select the right version.
 
 When reverting, you should **not** follow the database migration guides, as the
diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md
index 3e977749207..8ccdf8d0077 100644
--- a/doc/update/upgrading_postgresql_using_slony.md
+++ b/doc/update/upgrading_postgresql_using_slony.md
@@ -9,23 +9,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 This guide describes the steps one can take to upgrade their PostgreSQL database
 to the latest version without the need for hours of downtime. This guide assumes
 you have two database servers: one database server running an older version of
-PostgreSQL (e.g. 9.2.18) and one server running a newer version (e.g. 9.6.0).
+PostgreSQL (for example, 9.2.18) and one server running a newer version (for example, 9.6.0).
 
-For this process we use a PostgreSQL replication tool called
-["Slony"](https://www.slony.info/). Slony allows replication between different
+For this process, a PostgreSQL replication tool called
+[Slony](https://www.slony.info/) is used. Slony allows replication between different
 PostgreSQL versions and as such can be used to upgrade a cluster with a minimal
 amount of downtime.
 
-In various places we refer to the user `gitlab-psql`. This user should be the
-user used to run the various PostgreSQL OS processes. If you're using a
-different user (e.g. `postgres`) you should replace `gitlab-psql` with the name
+This guide often refers to the user `gitlab-psql`, which is the
+user used to run the various PostgreSQL OS processes. If you are using a
+different user (for example, `postgres`), replace `gitlab-psql` with the name
 of said user. This guide also assumes your database is called
 `gitlabhq_production`. If you happen to use a different database name you should
 change this accordingly.
 
 ## Database Dumps
 
-Slony only replicates data and not any schema changes. As a result we must
+Slony only replicates data and not any schema changes. As a result you must
 ensure that all databases have the same database structure.
 
 To do so, generate a dump of the current database. This dump only
@@ -40,10 +40,9 @@ If you're not using the Omnibus GitLab package you may have to adjust the paths
 `pg_dump` and the PostgreSQL installation directory to match the paths of your
 configuration.
 
-After the structure dump is generated we also need to generate a dump for the
+After the structure dump is generated, generate another dump for the
 `schema_migrations` table. This table doesn't have any primary keys and as such
-can't be replicated easily by Slony. To generate this dump run the following
-command on your active database server:
+can't be replicated by Slony. To generate a dump of the `schema_migrations` table, run the following command on your active database server:
 
 ```shell
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql/ -p 5432 -U gitlab-psql -a -t schema_migrations -f /tmp/migrations.sql gitlabhq_production
@@ -105,7 +104,7 @@ slonik version 2.2.5
 
 ## Slony User
 
-Next we must set up a PostgreSQL user that Slony can use to replicate your
+Next, set up a PostgreSQL user that Slony can use to replicate your
 database. To do so, sign in to your production database using `psql` using a
 super-user account. After signing in, run the following SQL queries:
 
@@ -123,8 +122,8 @@ later.
 
 ## Configuring Slony
 
-We can now start configuring Slony. Slony uses a configuration file for
-most of the work so we need to set this one up. This configuration file
+You can now start configuring Slony. Slony uses a configuration file for
+most of the work so it is important to set this up with care. Your configuration
 specifies where to put log files, how Slony should connect to the databases,
 etc.
 
@@ -138,11 +137,11 @@ sudo chown gitlab-psql:root /var/log/gitlab/slony /var/run/slony1 /var/opt/gitla
 ```
 
 Here `gitlab-psql` is the user used to run the PostgreSQL database processes. If
-you're using a different user you should replace this with the name of said
+you are using a different user you should replace this with the name of said
 user.
 
-Now that the directories are in place we can create the configuration file. For
-this we can use the following template:
+Now that the directories are in place you can create the configuration file
+by using the following template:
 
 ```perl
 if ($ENV{"SLONYNODES"}) {
@@ -179,15 +178,14 @@ if ($ENV{"SLONYSET"}) {
 1;
 ```
 
-In this configuration file you should replace a few placeholders before you can
-use it. The following placeholders should be replaced:
+Replace the following placeholders in this file to use it:
 
 - `OLD_HOST`: the address of the old database server.
 - `NEW_HOST`: the address of the new database server.
 - `SLONY_PASSWORD`: the password of the Slony user created earlier.
 - `TABLES`: the tables to replicate.
 
-The list of tables to replicate can be generated by running the following
+Generate the list of tables to replicate by running the following
 command on your old PostgreSQL database:
 
 ```shell
@@ -212,12 +210,12 @@ this output, don't just append it below it. The result looks like this:
 
 After you have the configuration file generated you must install it on both the
 old and new database. To do so, place it in
-`/var/opt/gitlab/postgresql/slony/slon_tools.conf` (for which we created the
+`/var/opt/gitlab/postgresql/slony/slon_tools.conf` (for which you created the
 directory earlier on).
 
-Now that the configuration file is in place we can _finally_ start replicating
-our database. First we must set up the schema in our new database. To do so make
-sure that the SQL files we generated earlier can be found in the `/tmp`
+Now that the configuration file is in place, you can _finally_ start replicating
+the database. First, set up the schema in the new database by making
+sure that the SQL files generated earlier are in the `/tmp`
 directory of the new server. After these files are in place start a `psql`
 session on this server:
 
@@ -250,8 +248,8 @@ following:
  ... more rows here ...
 ```
 
-Now we can initialize the required tables and what not that Slony uses for
-its replication process. To do so, run the following on the old database:
+Now you can initialize the required tables and other processes for
+the replication process. To do so, run the following on the old database:
 
 ```shell
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/slonik_init_cluster --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf | /opt/gitlab/embedded/bin/slonik
@@ -266,14 +264,14 @@ If all went well this produces something along the lines of:
 <stdin>:17: Please start a slon replication daemon for each node
 ```
 
-Next we need to start a replication node on every server. To do so, run the
+Next, start a replication node on every server. To do so, run the
 following on the old database:
 
 ```shell
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_start 1 --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf
 ```
 
-If all went well this produces output such as:
+This should produce an output like the following:
 
 ```plaintext
 Invoke slon for node 1 - /opt/gitlab/embedded/bin/slon -p /var/run/slony1/slony_replication_node1.pid -s 1000 -d2  slony_replication 'host=192.168.0.7 dbname=gitlabhq_production user=slony port=5432 password=hieng8ezohHuCeiqu0leeghai4aeyahp' > /var/log/gitlab/slony/node1/gitlabhq_production-2016-10-06.log 2>&1 &
@@ -282,7 +280,7 @@ PID [26740]
 Start the watchdog process as well...
 ```
 
-Next we need to run the following command on the _new_ database server:
+Next, run the following command on the _new_ database server:
 
 ```shell
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_start 2 --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf
@@ -290,14 +288,13 @@ sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_start 2 --conf /var/opt/gitlab
 
 This produces similar output if all went well.
 
-Next we need to tell the new database server what it should replicate. This can
-be done by running the following command on the _new_ database server:
+After Slony starts, you must tell the new database server what it should replicate. Run the following command on the _new_ database server:
 
 ```shell
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/slonik_create_set 1 --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf | /opt/gitlab/embedded/bin/slonik
 ```
 
-This should produce output along the lines of the following:
+This should produce an output like the following:
 
 ```plaintext
 <stdin>:11: Subscription set 1 (set1) created
@@ -310,7 +307,7 @@ This should produce output along the lines of the following:
 <stdin>:328: All tables added
 ```
 
-Finally we can start the replication process by running the following on the
+Finally, you can start the replication process by running the following on the
 _new_ database server:
 
 ```shell
@@ -357,17 +354,14 @@ main
 ```
 
 This script compares the sizes of the old and new database every minute and
-print the result to STDOUT as well as logging it to a file. Make sure to replace
+prints the results to STDOUT as well as logging it to a file. Make sure to replace
 `SLONY_PASSWORD`, `OLD_HOST`, and `NEW_HOST` with the correct values.
 
 ## Stopping Replication
 
-At some point, the two databases are in sync. If this is the case, you must plan
-for a few minutes of downtime. This small downtime window is used to stop the
-replication process, remove any Slony data from both databases, and restart
-GitLab so it can use the new database.
+Eventually, the two databases become in sync. At this point, there is a few minutes of downtime that you must plan for before the replicated database is available. During this time, the replication process should stop and all Slony data should be removed from both databases. After the replication process finishes, GitLab can restart and is able to use the newly-replicated database.
 
-First, let's stop all of GitLab. Omnibus users can do so by running the
+First, stop all of GitLab. Omnibus users can do so by running the
 following on their GitLab servers:
 
 ```shell
@@ -378,10 +372,10 @@ sudo gitlab-ctl stop mailroom
 
 If you have any other processes that use PostgreSQL, you should also stop those.
 
-After everything has been stopped, be sure to update any configuration settings
+After everything successfully stops, be sure to update any configuration settings
 and DNS records so they all point to the new database.
 
-When the settings have been taken care of, we need to stop the replication
+When the configuration is complete, stop the replication
 process. It's crucial that no new data is written to the databases at this point,
 as this data is discarded.
 
@@ -473,14 +467,14 @@ This corrects the ownership of sequences and reset the next value for the
 
 ## Removing Slony
 
-Next we need to remove all Slony related data. To do so, run the following
+The final step is to remove all Slony related data. To do so, run the following
 command on the _target_ server:
 
 ```shell
 sudo gitlab-psql gitlabhq_production -c "DROP SCHEMA _slony_replication CASCADE;"
 ```
 
-Once done you can safely remove any Slony related files (e.g. the log
+Once done you can safely remove any Slony related files (for example, the log
 directory), and uninstall Slony if desired. At this point you can start your
 GitLab instance again and if all went well it should be using your new database
 server.