Major README revisions for tone and stylesean_carroll-main-patch-28338

Shift commands from one-per-subheading to an unordered list, which is
easier to scan. Line wraps. Capitalization, spelling, word use. Move
the requirements section closer to the top of the page; we shouldn't
bury this information as the page gets longer.

1 files changed, 58 insertions, 67 deletions

diff --git a/README.md b/README.md
index 75374f5..a37cd96 100644
--- a/README.md
+++ b/README.md
@@ -4,26 +4,37 @@
 
 # GitLab Shell
 
-GitLab Shell is a SSH server, configured to handing git SSH sessions for GitLab. GitLab Shell is not a Unix shell nor a replacement for Bash or Zsh.
+GitLab Shell is a SSH server, configured to handle Git SSH sessions for GitLab.
+GitLab Shell is not a Unix shell, nor a replacement for Bash or Zsh:
 
-The purpose of GitLab Shell is to limit shell access to specific `git` commands, and provide authorization and transport for these commands.
+- It limits shell access to specific `git` commands.
+- It provides authorization and transport for these commands.
 
+## Requirements
+
+GitLab Shell is written in Go, and needs a Go compiler to build. It still requires
+Ruby to build and test, but not to run.
+
+Download and install the current version of Go from [golang.org](https://golang.org/dl/)
+
+We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy)
+of supporting the current stable version and the previous two major versions.
 
 ## Handling `git` SSH sessions
 
-When you access the GitLab server over SSH then GitLab Shell will:
+When you access the GitLab server over SSH, GitLab Shell:
 
-1. Limit you to `git push` and `git pull`, `git fetch` commands only
-1. Call the GitLab Rails API to check if you are authorized, and what Gitaly server your repository is on
-1. Copy data back and forth between the SSH client and the Gitaly server
+1. Limits you to `git push`, `git pull`, and `git fetch` commands only.
+1. Calls the GitLab Rails API to check if you are authorized, and what Gitaly server your repository is on.
+1. Copies data back and forth between the SSH client and the Gitaly server.
 
 ### `git pull` over SSH
 
-git pull over SSH -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> establish Gitaly session
+Git pull over SSH -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> establish Gitaly session
 
 ### `git push` over SSH
 
-git push over SSH -> gitlab-shell (git command is not executed yet) -> establish Gitaly session -> (in Gitaly) gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push
+Git push over SSH -> gitlab-shell (git command is not executed yet) -> establish Gitaly session -> (in Gitaly) gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push
 
 For more details see [Architecture](doc/architecture.md)
 
@@ -33,87 +44,67 @@ GitLab Shell modifies the `authorized_keys` file on the client machine.
 
 - TODO some details needed here.
 
-### Runs on Port 22
+### Runs on port 22
 
-GitLab Shell runs on `port 22` on an Omnibus installation. A "regular" SSH service would need to be configured to run on an alternative port.
+GitLab Shell runs on `port 22` on an Omnibus installation. To use a regular SSH
+service, configure it on an alternative port.
 
-### Accessing GitLab using `https`
+### Access GitLab with `https`
 
-If you access a GitLab server over HTTP(S) you end up in [gitlab-workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse).
+If you access a GitLab server over HTTP(S) you end up in
+[`gitlab-workhorse`](https://gitlab.com/gitlab-org/gitlab-workhorse).
 
 ## `gitlab-sshd`
 
-See [gitlab-sshd](doc/gitlab-sshd)
-
-## Requirements
-
-GitLab Shell is written in Go, and needs a Go compiler to build. It still requires
-Ruby to build and test, but not to run.
-
-Download and install the current version of Go from https://golang.org/dl/
-
-We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy)
-of supporting the current stable version and the previous two major versions.
-
-### Check
-
-Checks if GitLab API access and redis via internal API can be reached:
-
-    make check
-
-### Compile
-
-Builds the `gitlab-shell` binaries, placing them into `bin/`.
-
-    make compile
-
-### Install
-
-Builds the `gitlab-shell` binaries and installs them onto the filesystem. The
-default location is `/usr/local`, but can be controlled by use of the `PREFIX`
-and `DESTDIR` environment variables.
-
-    make install
-
-### Setup
-
-This command is intended for use when installing GitLab from source on a single
-machine. In addition to compiling the gitlab-shell binaries, it ensures that
-various paths on the filesystem exist with the correct permissions. Do not run
-it unless instructed to by your installation method documentation.
+See [`gitlab-sshd`](doc/gitlab-sshd).
 
-    make setup
+## Commands
 
+- `make check`: Checks if GitLab API access and Redis (via internal API) can be reached
+- `make compile`: Builds the `gitlab-shell` binaries, placing them into `bin/`.
+- `make install`: Builds the `gitlab-shell` binaries and installs them onto the
+  file system. The default location is `/usr/local`, but you can change it with the `PREFIX`
+  and `DESTDIR` environment variables.
+- `make setup`: Don't run this command unless instructed to by your installation method
+  documentation. Used when installing GitLab from source on a single machine. Compiles
+  the `gitlab-shell` binaries, and ensures that file system paths exist and contain
+  correct permissions.
 
 ### Testing
 
 Run tests:
 
-    bundle install
-    make test
+```shell
+bundle install
+make test
+```
 
 Run `gofmt`:
 
-    make verify
+```shell
+make verify
+```
 
 Run both test and verify (the default Makefile target):
 
-    bundle install
-    make validate
+```shell
+bundle install
+make validate
+```
 
 ### Gitaly
 
 Some tests need a Gitaly server. The
-[`docker-compose.yml`](./docker-compose.yml) file will run Gitaly on
-port 8075. To tell the tests where Gitaly is, set
-`GITALY_CONNECTION_INFO`:
+[`docker-compose.yml`](docker-compose.yml) file runs Gitaly on port 8075.
+To tell the tests the location of Gitaly, set `GITALY_CONNECTION_INFO`:
 
-    export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}'
-    make test
+```plaintext
+export GITALY_CONNECTION_INFO='{"address": "tcp://localhost:8075", "storage": "default"}'
+make test
+```
 
-If no `GITALY_CONNECTION_INFO` is set, the test suite will still run, but any
-tests requiring Gitaly will be skipped. They will always run in the CI
-environment.
+If no `GITALY_CONNECTION_INFO` is set, the test suite still runs, but any
+tests requiring Gitaly are skipped. These tests always run in the CI environment.
 
 ## References
 
@@ -125,12 +116,12 @@ GitLab supports Git LFS authentication through SSH.
 
 ## Releasing
 
-See [PROCESS.md](./PROCESS.md)
+See [PROCESS.md](PROCESS.md)
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-See [LICENSE](./LICENSE).
+See [LICENSE](LICENSE).