Merge branch 'msj-version-reqs-docs' into 'master'

Update how documentation describes minimum software versions

Closes #195693

See merge request gitlab-org/gitlab!22622

doc/install/requirements.md

@@ -38,14 +38,40 @@ GitLab is developed for Linux-based operating systems.
 It does **not** run on Microsoft Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab/issues/22337).
 Please consider using a virtual machine to run GitLab.
 
-## Ruby versions
+## Software requirements
 
-GitLab requires Ruby (MRI) 2.6. Support for Ruby versions below 2.6 (2.4, 2.5) will stop with GitLab 12.2.
+### Ruby versions
 
-You will have to use the standard MRI implementation of Ruby.
-We love [JRuby](https://www.jruby.org/) and [Rubinius](https://rubinius.com) but GitLab
+GitLab requires Ruby (MRI) 2.6. Beginning in GitLab 12.2, we  no longer support Ruby 2.5 and lower.
+
+You must use the standard MRI implementation of Ruby.
+We love [JRuby](https://www.jruby.org/) and [Rubinius](https://rubinius.com), but GitLab
 needs several Gems that have native extensions.
 
+### Go versions
+
+The minimum required Go version is 1.12.
+
+### Git versions
+
+GitLab 11.11 and higher only supports Git 2.21.x and newer, and
+[dropped support for older versions](https://gitlab.com/gitlab-org/gitlab-foss/issues/54255).
+
+### Node.js versions
+
+Beginning in GitLab 11.8, we only support Node.js 8.10.0 or higher, and dropped
+support for Node.js 6.
+
+We recommend Node 12.x, as it is faster.
+
+GitLab uses [webpack](https://webpack.js.org/) to compile frontend assets, which requires a minimum
+version of Node.js 8.10.0.
+
+You can check which version you are running with `node -v`. If you are running
+a version older than `v8.10.0`, you need to update to a newer version. You
+can find instructions to install from community maintained packages or compile
+from source at the [Node.js website](https://nodejs.org/en/download).
+
 ## Hardware requirements
 
 ### Storage

doc/update/upgrading_from_source.md

@@ -82,24 +82,15 @@ Install Bundler:
 sudo gem install bundler --no-document --version '< 2'
 ```
 
-### 4. Update Node
+### 4. Update Node.js
 
-NOTE: Beginning in GitLab 11.8, we only support node 8 or higher, and dropped
-support for node 6. Be sure to upgrade if necessary.
+NOTE: To check the minimum required Node.js version, see [Node.js versions](../install/requirements.md#nodejs-versions).
 
-GitLab utilizes [webpack](https://webpack.js.org/) to compile frontend assets.
-This requires a minimum version of node v8.10.0.
-
-You can check which version you are running with `node -v`. If you are running
-a version older than `v8.10.0` you will need to update to a newer version. You
-can find instructions to install from community maintained packages or compile
-from source at the nodejs.org website.
-
-<https://nodejs.org/en/download/>
-
-GitLab also requires the use of yarn `>= v1.10.0` to manage JavaScript
+GitLab also requires the use of Yarn `>= v1.10.0` to manage JavaScript
 dependencies.
 
+In Debian or Ubuntu:
+
 ```bash
 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
@@ -107,34 +98,33 @@ sudo apt-get update
 sudo apt-get install yarn
 ```
 
-More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install).
+More information can be found on the [Yarn website](https://yarnpkg.com/en/docs/install).
 
 ### 5. Update Go
 
-NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go
-1.9.x. Be sure to upgrade your installation if necessary.
+NOTE: 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`.
 
-Download and install Go:
+Download and install Go (for Linux, 64-bit):
 
 ```bash
 # Remove former Go installation folder
 sudo rm -rf /usr/local/go
 
-curl --remote-name --progress https://dl.google.com/go/go1.11.10.linux-amd64.tar.gz
-echo 'aefaa228b68641e266d1f23f1d95dba33f17552ba132878b65bb798ffa37e6d0  go1.11.10.linux-amd64.tar.gz' | shasum -a256 -c - && \
-  sudo tar -C /usr/local -xzf go1.11.10.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/
-rm go1.11.10.linux-amd64.tar.gz
+rm go1.13.5.linux-amd64.tar.gz
+
 ```
 
 ### 6. Update Git
 
-NOTE: **Note:**
-GitLab 11.11 and higher only supports Git 2.21.x and newer, and
-[dropped support for older versions](https://gitlab.com/gitlab-org/gitlab-foss/issues/54255).
-Be sure to upgrade your installation if necessary.
+NOTE: To check the minimum required Git version, see [Git versions](../install/requirements.md#git-versions).
+
+In Debian or Ubuntu:
 
 ```bash
 # Make sure Git is version 2.21.0 or higher
@@ -254,9 +244,8 @@ sudo -u git -H make
 
 #### New configuration options for `gitlab.yml`
 
-There might be configuration options available for [`gitlab.yml`][yaml]. View
-them with the command below and apply them manually to your current
-`gitlab.yml`:
+There might be configuration options available for [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example)).
+View them with the command below and apply them manually to your current `gitlab.yml`:
 
 ```sh
 cd /home/git/gitlab
@@ -282,7 +271,7 @@ 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 Apache instead of NGINX please see the updated [Apache templates].
+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
 via [`/etc/default/gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/support/init.d/gitlab.default.example#L38).
@@ -296,13 +285,13 @@ add the following line to `config/initializers/smtp_settings.rb`:
 ActionMailer::Base.delivery_method = :smtp
 ```
 
-See [smtp_settings.rb.sample] as an example.
+See [smtp_settings.rb.sample](https://gitlab.com/gitlab-org/gitlab/blob/master/config/initializers/smtp_settings.rb.sample#L13) as an example.
 
 #### Init script
 
 There might be new configuration options available for
-[`gitlab.default.example`][gl-example]. View them with the command below and
-apply them manually to your current `/etc/default/gitlab`:
+[`gitlab.default.example`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/support/init.d/gitlab.default.example).
+View them with the command below and apply them manually to your current `/etc/default/gitlab`:
 
 ```sh
 cd /home/git/gitlab
@@ -389,17 +378,19 @@ Example:
 Additional instructions here.
 -->
 
-## Things went south? Revert to previous version
+## Troubleshooting
 
 ### 1. Revert the code to the previous version
 
-To revert to a previous version, you'll need to following the upgrading guides
-for the previous version. If you upgraded to 11.8 and want to revert back to
-11.7, you'll need to follow the guides for upgrading from 11.6 to 11.7. You can
+To revert to a previous version, you need to 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
 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
-backup is already migrated to the previous version.
+When reverting, you should **not** follow the database migration guides, as the
+backup has already been migrated to the previous version.
 
 ### 2. Restore from the backup
 
@@ -409,9 +400,4 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
 ```
 
-If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above.
-
-[yaml]: https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example
-[gl-example]: https://gitlab.com/gitlab-org/gitlab/blob/master/lib/support/init.d/gitlab.default.example
-[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab/blob/master/config/initializers/smtp_settings.rb.sample#L13
-[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache
+If you have more than one backup `*.tar` file, add `BACKUP=timestamp_of_backup` to the above.