README & CONTRIBUTING updates (#1167)

* Quicker failure and description when invalid token supplied

Fixes #1156

When users export a GitHub API token that has insufficient privleges
or has been revoked, we have been using a catch all error with retry
to handle it. This change adds a new error type for bad credentials
and does not retry.

Test plan:
There are no unit tests that cover this, however, you can test the
change by supplying a revoked token and attempting to load a GitHub
repo.

* Minor: reunite comment with relevant code block

* Update Changelog: Fail quicker and with information when using invalid GH token (#1161)

* Documentation updates

Added note on Changelog update format, SSH key requirements, and formatted the console (CLI) blocks a little better.

* Minor formatting fixes

* Revert a line wrap commit as it is not appropriate on README.md

* Removed prompt tokens and changed non-visible formatting

CONTRIBUTING.md

@@ -124,7 +124,8 @@ This is the same set of tests that is run on our CI system, CircleCI.
 If your patch makes a change that would be visible or interesting to a
 user of SourceCred—for example, fixing a bug—please add a description of
 the change under the `[Unreleased]` heading of `CHANGELOG.md`. Your new
-change should be the first entry in the section.
+change should be the first entry in the section. The format of your
+entry should be: ```<description of change> (#<PR number>)```.
 
 ## When writing commit messages
 

README.md

@@ -32,6 +32,7 @@ First, make sure that you have the following dependencies:
   - Install [Node] (tested on v12.x.x and v10.x.x).
   - Install [Yarn] (tested on v1.7.0).
   - Create a [GitHub API token]. No special permissions are required.
+  - Ensure that you have an SSH key (`id_rsa`) for `git` to use. On unix-like systems, this is usually stored in `~/.ssh/`. If you do not, you can generate one by following these [instructions](https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
   - For macOS users: Ensure that your environment provides GNU
     coreutils. [See this comment for details about what, how, and
     why.][macos-gnu]
@@ -44,27 +45,31 @@ First, make sure that you have the following dependencies:
 
 Then, run the following commands to clone and build SourceCred:
 
-```
+```Bash
 git clone https://github.com/sourcecred/sourcecred.git
 cd sourcecred
 yarn install
 yarn backend
 export SOURCECRED_GITHUB_TOKEN=YOUR_GITHUB_TOKEN
 node bin/sourcecred.js load REPO_OWNER/REPO_NAME
-# this loads sourcecred data for a particular repository
+```
-# it can take a few mins to run and will exit when finished
+
+Loading a repo can take a few minutes. When it is finished, it will exit. Next, we can start sourcecred:
+
+```Bash
 yarn start
-# then navigate to localhost:8080 in your browser
 ```
 
-For example, if you wanted to look at cred for [ipfs/js-ipfs], you could run:
+Finally, we can navigate a browser window to `localhost:8080` to view generated data.
 
-```
+#### Examples
-$ export SOURCECRED_GITHUB_TOKEN=0000000000000000000000000000000000000000
-$ node bin/sourcecred.js load ipfs/js-ipfs
-```
 
-replacing the big string of zeros with your actual token.
+If you wanted to look at cred for [ipfs/js-ipfs], you could run:
+
+```Bash
+export SOURCECRED_GITHUB_TOKEN=YOUR_GITHUB_TOKEN
+node bin/sourcecred.js load ipfs/js-ipfs
+```
 
 [ipfs/js-ipfs]: https://github.com/ipfs/js-ipfs
 
@@ -72,7 +77,7 @@ You can also combine data from multiple repositories into a single graph.
 To do so, pass multiple repositories to the `load` command, and specify an “output name” for the repository.
 For instance, the invocation
 
-```
+```Bash
 node bin/sourcecred.js load ipfs/js-ipfs ipfs/go-ipfs --output ipfs/meta-ipfs
 ```