Add latest changes from gitlab-org/gitlab@13-7-stable-eev13.7.0-rc42

7 files changed, 88 insertions, 89 deletions

diff --git a/doc/update/README.md b/doc/update/README.md
index 0534d793613..45cac3ec8ca 100644
--- a/doc/update/README.md
+++ b/doc/update/README.md
@@ -1,7 +1,7 @@
 ---
 stage: Enablement
 group: Distribution
-info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
 # Upgrading GitLab
@@ -33,7 +33,7 @@ official ways to update GitLab:
 ### Linux packages (Omnibus GitLab)
 
 The [Omnibus update guide](https://docs.gitlab.com/omnibus/update/)
-contains the steps needed to update a package installed by GitLab's official
+contains the steps needed to update a package installed by official GitLab
 repositories.
 
 There are also instructions when you want to
@@ -109,7 +109,7 @@ Sidekiq::ScheduledSet.new.select { |r| r.klass == 'BackgroundMigrationWorker' }.
 
 ### What do I do if my background migrations are stuck?
 
-CAUTION: **Warning:**
+WARNING:
 The following operations can disrupt your GitLab performance.
 
 It is safe to re-execute these commands, especially if you have 1000+ pending jobs which would likely overflow your runtime memory.
@@ -266,7 +266,7 @@ Below you can find some guides to help you change GitLab editions.
 
 ### Community to Enterprise Edition
 
-NOTE: **Note:**
+NOTE:
 The following guides are for subscribers of the Enterprise Edition only.
 
 If you wish to upgrade your GitLab installation from Community to Enterprise
@@ -276,7 +276,7 @@ Edition, follow the guides below based on the installation method:
   to a version upgrade: stop the server, get the code, update configuration files for
   the new functionality, install libraries and do migrations, update the init
   script, start the application and check its status.
-- [Omnibus CE to EE](https://docs.gitlab.com/omnibus/update/README.html#updating-community-edition-to-enterprise-edition) - Follow this guide to update your Omnibus
+- [Omnibus CE to EE](https://docs.gitlab.com/omnibus/update/README.html#update-community-edition-to-enterprise-edition) - Follow this guide to update your Omnibus
   GitLab Community Edition to the Enterprise Edition.
 
 ### Enterprise to Community Edition
@@ -310,6 +310,10 @@ installation-specific upgrade instructions, based on how you installed GitLab:
 - [Linux packages (Omnibus GitLab)](https://docs.gitlab.com/omnibus/update/README.html#version-specific-changes)
 - [Helm charts](https://docs.gitlab.com/charts/installation/upgrade.html)
 
+NOTE:
+Specific information that follow related to Ruby and Git versions do not apply to [Omnibus installations](https://docs.gitlab.com/omnibus/)
+and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with appropriate Ruby and Git versions and are not using system binaries for Ruby and Git. There is no need to install Ruby or Git when utilizing these two approaches.
+
 ### 13.6.0
 
 Ruby 2.7.2 is required. GitLab will not start with Ruby 2.6.6 or older versions.
diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md
index 10c1a5017b5..613df2c3a84 100644
--- a/doc/update/mysql_to_postgresql.md
+++ b/doc/update/mysql_to_postgresql.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/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
 # Migrating from MySQL to PostgreSQL
@@ -11,7 +11,7 @@ migrate it to a PostgreSQL database.
 
 ## Requirements
 
-NOTE: **Note:**
+NOTE:
 Support for MySQL was removed in GitLab 12.1. This procedure should be performed
 **before** installing GitLab 12.1.
 
@@ -51,7 +51,7 @@ For other distributions, follow the instructions in PostgreSQL's
 [download page](https://www.postgresql.org/download/) to add their repository
 and then install `pgloader`.
 
-If you are migrating to a Docker based installation, you will need to install
+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.
 
 1. Start a shell session in the context of the running container:
@@ -69,7 +69,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'll first
+For [Omnibus GitLab packages](https://about.gitlab.com/install/), you first
 need to enable the bundled PostgreSQL:
 
 1. Stop GitLab:
@@ -84,13 +84,13 @@ need to enable the bundled PostgreSQL:
    postgresql['enable'] = true
    ```
 
-1. Edit `/etc/gitlab/gitlab.rb` to use the bundled PostgreSQL. Please check
-   all the settings beginning with `db_`, such as `gitlab_rails['db_adapter']`
-   and alike. You could just comment all of them out so that we'll just use
-   the defaults.
+1. Edit `/etc/gitlab/gitlab.rb` to use the bundled PostgreSQL. Review all of the
+   settings beginning with `db_` (such as `gitlab_rails['db_adapter']`). To use
+   the default values, you can comment all of them out.
 
 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
    for the changes to take effect.
+
 1. Start Unicorn and PostgreSQL so that we can prepare the schema:
 
    ```shell
@@ -110,9 +110,9 @@ need to enable the bundled PostgreSQL:
    sudo gitlab-ctl stop unicorn
    ```
 
-After these steps, you'll have a fresh PostgreSQL database with up-to-date schema.
+After these steps, you have a fresh PostgreSQL database with up-to-date schema.
 
-Next, we'll use `pgloader` to migrate the data from the old MySQL database to the
+Next, use `pgloader` to migrate the data from the old MySQL database to the
 new PostgreSQL one:
 
 1. Save the following snippet in a `commands.load` file, and edit with your
@@ -178,7 +178,7 @@ You can now verify that everything works as expected by visiting GitLab.
 
 ## Source installations
 
-For installations from source that use MySQL, you'll first need to
+For installations from source that use MySQL, you must first
 [install PostgreSQL and create a database](../install/installation.md#6-database).
 
 After the database is created, go on with the following steps:
@@ -211,9 +211,9 @@ After the database is created, go on with the following steps:
    sudo -u git -H bundle exec rake db:create db:migrate RAILS_ENV=production
    ```
 
-After these steps, you'll have a fresh PostgreSQL database with up-to-date schema.
+After these steps, you have a fresh PostgreSQL database with up-to-date schema.
 
-Next, we'll use `pgloader` to migrate the data from the old MySQL database to the
+Next, use `pgloader` to migrate the data from the old MySQL database to the
 new PostgreSQL one:
 
 1. Save the following snippet in a `commands.load` file, and edit with your
diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md
index 081df16be81..754265a23cf 100644
--- a/doc/update/patch_versions.md
+++ b/doc/update/patch_versions.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/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 comments: false
 ---
 
diff --git a/doc/update/restore_after_failure.md b/doc/update/restore_after_failure.md
index e35d7bff562..0625cc5a68f 100644
--- a/doc/update/restore_after_failure.md
+++ b/doc/update/restore_after_failure.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/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
 # Restoring from backup after a failed upgrade
@@ -65,7 +65,7 @@ sudo gitlab-rake gitlab:db:mark_migration_complete[20151103134857]
 ```
 
 Once the migration is successfully marked, run the Rake `db:migrate` task again.
-You will likely have to repeat this process several times until all failed
+You might need to repeat this process several times until all failed
 migrations are marked complete.
 
 ### GitLab < 8.6
@@ -86,5 +86,5 @@ exit
 ```
 
 Once the migration is successfully marked, run the Rake `db:migrate` task again.
-You will likely have to repeat this process several times until all failed
+You might need to repeat this process several times until all failed
 migrations are marked complete.
diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md
index 71d857ce18f..9a75326009c 100644
--- a/doc/update/upgrading_from_ce_to_ee.md
+++ b/doc/update/upgrading_from_ce_to_ee.md
@@ -1,13 +1,13 @@
 ---
 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/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 comments: false
 ---
 
 # Upgrading from Community Edition to Enterprise Edition from source
 
-NOTE: **Note:**
+NOTE:
 In the past we used separate documents for upgrading from
 Community Edition to Enterprise Edition. These documents can be found in the
 [`doc/update` directory of Enterprise Edition's source
@@ -128,7 +128,7 @@ sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
 
 Certain versions of GitLab may require you to perform additional steps when
 upgrading from Community Edition to Enterprise Edition. Should such steps be
-necessary, they will listed per version below.
+necessary, they are listed per version below.
 
 <!--
 Example:
diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md
index 4eedc9bb89f..770eade6542 100644
--- a/doc/update/upgrading_from_source.md
+++ b/doc/update/upgrading_from_source.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/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 comments: false
 ---
 
 # Upgrading Community Edition and Enterprise Edition from source
 
-NOTE: **Note:**
-Users wishing to upgrade to 12.0.0 will have to take some extra steps. See the
+NOTE:
+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
@@ -45,7 +45,7 @@ specific guidelines (should there be any) are covered separately.
 
 ### 1. Backup
 
-NOTE: If you installed GitLab from source, make sure `rsync` is installed.
+If you installed GitLab from source, make sure `rsync` is installed.
 
 ```shell
 cd /home/git/gitlab
@@ -61,7 +61,8 @@ sudo service gitlab stop
 
 ### 3. Update Ruby
 
-NOTE: Beginning in GitLab 13.6, we only support Ruby 2.7 or higher, and dropped
+NOTE:
+Beginning in GitLab 13.6, we only support Ruby 2.7 or higher, and dropped
 support for Ruby 2.6. Be sure to upgrade if necessary.
 
 You can check which version you are running with `ruby -v`.
@@ -70,7 +71,7 @@ Download Ruby and compile it:
 
 ```shell
 mkdir /tmp/ruby && cd /tmp/ruby
-curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz
+curl --remote-name --progress "https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz"
 echo 'cb9731a17487e0ad84037490a6baf8bfa31a09e8  ruby-2.7.2.tar.gz' | shasum -c - && tar xzf ruby-2.7.2.tar.gz
 cd ruby-2.7.2
 
@@ -81,7 +82,7 @@ sudo make install
 
 ### 4. Update Node.js
 
-NOTE: To check the minimum required Node.js version, see [Node.js versions](../install/requirements.md#nodejs-versions).
+To check the minimum required Node.js version, see [Node.js versions](../install/requirements.md#nodejs-versions).
 
 GitLab also requires the use of Yarn `>= v1.10.0` to manage JavaScript
 dependencies.
@@ -89,7 +90,7 @@ dependencies.
 In Debian or Ubuntu:
 
 ```shell
-curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
+curl --silent --show-error "https://dl.yarnpkg.com/debian/pubkey.gpg" | sudo apt-key add -
 echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
 sudo apt-get update
 sudo apt-get install yarn
@@ -99,7 +100,7 @@ More information can be found on the [Yarn website](https://classic.yarnpkg.com/
 
 ### 5. Update Go
 
-NOTE: To check the minimum required Go version, see [Go versions](../install/requirements.md#go-versions).
+To check the minimum required Go version, see [Go versions](../install/requirements.md#go-versions).
 
 You can check which version you are running with `go version`.
 
@@ -109,7 +110,7 @@ Download and install Go (for Linux, 64-bit):
 # Remove former Go installation folder
 sudo rm -rf /usr/local/go
 
-curl --remote-name --progress https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz
+curl --remote-name --progress "https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz"
 echo '512103d7ad296467814a6e3f635631bd35574cab3369a97a323c9a585ccaa569  go1.13.5.linux-amd64.tar.gz' | shasum -a256 -c - && \
   sudo tar -C /usr/local -xzf go1.13.5.linux-amd64.tar.gz
 sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/
@@ -119,7 +120,7 @@ rm go1.13.5.linux-amd64.tar.gz
 
 ### 6. Update Git
 
-CAUTION: **Caution:**
+WARNING:
 From GitLab 13.1, you must use at least Git v2.24 (previous minimum version was v2.22).
 Git v2.28 is recommended.
 
@@ -139,7 +140,7 @@ sudo apt-get remove git-core
 sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev build-essential
 
 # Download and compile pcre2 from source
-curl --silent --show-error --location https://ftp.pcre.org/pub/pcre/pcre2-10.33.tar.gz --output pcre2.tar.gz
+curl --silent --show-error --location "https://ftp.pcre.org/pub/pcre/pcre2-10.33.tar.gz" --output pcre2.tar.gz
 tar -xzf pcre2.tar.gz
 cd pcre2-10.33
 chmod +x configure
@@ -149,7 +150,7 @@ make install
 
 # Download and compile from source
 cd /tmp
-curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.29.0.tar.gz
+curl --remote-name --location --progress "https://www.kernel.org/pub/software/scm/git/git-2.29.0.tar.gz"
 echo 'fa08dc8424ef80c0f9bf307877f9e2e49f1a6049e873530d6747c2be770742ff  git-2.29.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.29.0.tar.gz
 cd git-2.29.0/
 ./configure --with-libpcre
@@ -163,7 +164,7 @@ sudo make prefix=/usr/local install
 
 ### 7. Update PostgreSQL
 
-CAUTION: **Caution:**
+WARNING:
 From GitLab 13.0, you must use at least PostgreSQL 11.
 
 The latest version of GitLab might depend on a more recent PostgreSQL version than what you are currently running (see the [PostgreSQL requirements](../install/requirements.md#postgresql-requirements)).
@@ -210,17 +211,12 @@ sudo -u git -H make build
 
 ### 10. Update GitLab Workhorse
 
-Install and compile GitLab Workhorse. GitLab Workhorse uses
-[GNU Make](https://www.gnu.org/software/make/).
-If you are not using Linux you may have to run `gmake` instead of
-`make` below.
+Install and compile GitLab Workhorse.
 
 ```shell
-cd /home/git/gitlab-workhorse
+cd /home/git/gitlab
 
-sudo -u git -H git fetch --all --tags --prune
-sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION)
-sudo -u git -H make
+sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production
 ```
 
 ### 11. Update Gitaly
@@ -284,12 +280,12 @@ longer handles setting 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
-will need to let GitLab Workhorse listen on a TCP port. You can do this
+must let GitLab Workhorse listen on a TCP port. You can do this
 via [`/etc/default/gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/support/init.d/gitlab.default.example#L38).
 
 #### SMTP configuration
 
-If you're installing from source and use SMTP to deliver mail, you will need to
+If you're installing from source and use SMTP to deliver mail, you must
 add the following line to `config/initializers/smtp_settings.rb`:
 
 ```ruby
diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md
index 4d8b58cc3af..89df7090977 100644
--- a/doc/update/upgrading_postgresql_using_slony.md
+++ b/doc/update/upgrading_postgresql_using_slony.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/engineering/ux/technical-writing/#designated-technical-writers
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
 # Upgrading PostgreSQL Using Slony
@@ -11,12 +11,12 @@ 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).
 
-For this process we'll use a PostgreSQL replication tool called
+For this process we use a PostgreSQL replication tool called
 ["Slony"](https://www.slony.info/). 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'll refer to the user `gitlab-psql`. This user should be the
+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
 of said user. This guide also assumes your database is called
@@ -28,15 +28,15 @@ change this accordingly.
 Slony only replicates data and not any schema changes. As a result we must
 ensure that all databases have the same database structure.
 
-To do so we'll generate a dump of our current database. This dump will only
-contain the structure, not any data. To generate this dump run the following
+To do so, generate a dump of the current database. This dump only
+contains the structure, not any data. To generate this dump 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 -s -f /tmp/structure.sql gitlabhq_production
 ```
 
-If you're not using GitLab's Omnibus package you may have to adjust the paths to
+If you're not using the Omnibus GitLab package you may have to adjust the paths to
 `pg_dump` and the PostgreSQL installation directory to match the paths of your
 configuration.
 
@@ -49,20 +49,20 @@ command on your active database server:
 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
 ```
 
-Next we'll need to move these files somewhere accessible by the new database
-server. The easiest way is to simply download these files to your local system:
+Next, move these files somewhere accessible by the new database
+server. The easiest way is to download these files to your local system:
 
 ```shell
 scp your-user@production-database-host:/tmp/*.sql /tmp
 ```
 
-This will copy all the SQL files located in `/tmp` to your local system's
+This copies all the SQL files located in `/tmp` to your local system's
 `/tmp` directory. Once copied you can safely remove the files from the database
 server.
 
 ## Installing Slony
 
-Slony will be used to upgrade the database without requiring a long downtime.
+Use Slony to upgrade the database without requiring a long downtime.
 Slony can be downloaded from <https://www.slony.info/>. If you have installed
 PostgreSQL using your operating system's package manager you may also be able to
 install Slony using said package manager.
@@ -94,7 +94,7 @@ test -f /opt/gitlab/embedded/bin/slonik_init_cluster && echo 'Slony Perl tools a
 ```
 
 This assumes Slony was installed to `/opt/gitlab/embedded`. If Slony was
-installed properly the output of these commands will be (the mentioned `slonik`
+installed properly the output of these commands is (the mentioned `slonik`
 version may be different):
 
 ```plaintext
@@ -106,8 +106,8 @@ slonik version 2.2.5
 ## Slony User
 
 Next we must set up a PostgreSQL user that Slony can use to replicate your
-database. To do so, log in to your production database using `psql` using a
-super user account. Once done run the following SQL queries:
+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:
 
 ```sql
 CREATE ROLE slony WITH SUPERUSER LOGIN REPLICATION ENCRYPTED PASSWORD 'password string here';
@@ -115,20 +115,20 @@ ALTER ROLE slony SET statement_timeout TO 0;
 ```
 
 Make sure you replace "password string here" with the actual password for the
-user. A password is *required*. This user must be created on _both_ the old and
+user. A password is required. This user must be created on both the old and
 new database server using the same password.
 
-Once the user has been created make sure you note down the password as we will
-need it later on.
+After creating the user, be sure to note the password, as the password is needed
+later.
 
 ## Configuring Slony
 
-Now we can finally start configuring Slony. Slony uses a configuration file for
-most of the work so we'll need to set this one up. This configuration file
+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
 specifies where to put log files, how Slony should connect to the databases,
 etc.
 
-First we'll need to create some required directories and set the correct
+First, create some required directories and set the correct
 permissions. To do so, run the following commands on both the old and new
 database server:
 
@@ -199,8 +199,7 @@ appropriate path to the `psql` executable.
 
 The above command outputs a list of tables in a format that can be copy-pasted
 directly into the above configuration file. Make sure to _replace_ `TABLES` with
-this output, don't just append it below it. Once done you'll end up with
-something like this:
+this output, don't just append it below it. The result looks like this:
 
 ```perl
 "pkeyedtables" => [
@@ -251,14 +250,14 @@ following:
  ... more rows here ...
 ```
 
-Now we can initialize the required tables and what not that Slony will use for
+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:
 
 ```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
 ```
 
-If all went well this will produce something along the lines of:
+If all went well this produces something along the lines of:
 
 ```plaintext
 <stdin>:10: Set up replication nodes
@@ -274,7 +273,7 @@ following on the old database:
 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 will produce output such as:
+If all went well this produces output such as:
 
 ```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 &
@@ -289,7 +288,7 @@ Next we need to run the following command on the _new_ database server:
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_start 2 --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf
 ```
 
-This will produce similar output if all went well.
+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:
@@ -324,7 +323,7 @@ This should produce the following output:
 <stdin>:6: Subscribed nodes to set 1
 ```
 
-At this point the new database server will start replicating the data of the old
+At this point the new database server starts replicating the data of the old
 database server. This process can take anywhere from a few minutes to hours, if
 not days. Unfortunately Slony itself doesn't really provide a way of knowing
 when the two databases are in sync. To get an estimate of the progress you can
@@ -357,19 +356,19 @@ function main {
 main
 ```
 
-This script will compare the sizes of the old and new database every minute and
+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
 `SLONY_PASSWORD`, `OLD_HOST`, and `NEW_HOST` with the correct values.
 
 ## Stopping Replication
 
-At some point the two databases are in sync. Once this is the case you'll need
-to 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, restart
-GitLab so it can use the new database, etc.
+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.
 
 First, let's stop all of GitLab. Omnibus users can do so by running the
-following on their GitLab server(s):
+following on their GitLab servers:
 
 ```shell
 sudo gitlab-ctl stop unicorn
@@ -377,14 +376,14 @@ sudo gitlab-ctl stop sidekiq
 sudo gitlab-ctl stop mailroom
 ```
 
-If you have any other processes that use PostgreSQL you should also stop those.
+If you have any other processes that use PostgreSQL, you should also stop those.
 
-Once everything has been stopped you should update any configuration settings,
-DNS records, etc so they all point to the new database.
+After everything has been stopped, be sure to update any configuration settings
+and DNS records so they all point to the new database.
 
-Once the settings have been taken care of we need to stop the replication
-process. It's crucial that no new data is written to the databases at this point
-as this data will be lost.
+When the settings have been taken care of, we need to stop the replication
+process. It's crucial that no new data is written to the databases at this point,
+as this data is discarded.
 
 To stop replication, run the following on both database servers:
 
@@ -392,7 +391,7 @@ To stop replication, run the following on both database servers:
 sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_kill --conf /var/opt/gitlab/postgresql/slony/slon_tools.conf
 ```
 
-This will stop all the Slony processes on the host the command was executed on.
+This stops all the Slony processes on the host the command was executed on.
 
 ## Resetting Sequences
 
@@ -469,7 +468,7 @@ Upload this script to the _target_ server and execute it as follows:
 bash path/to/the/script/above.sh
 ```
 
-This will correct the ownership of sequences and reset the next value for the
+This corrects the ownership of sequences and reset the next value for the
 `id` column to the next available value.
 
 ## Removing Slony