impl: update README to explain how to use Netlify (#898)

- Document that we use Netlify instead of GitHub Pages now.
- Update the "developing and testing locally" instructions to use
  `netlify dev` instead of running Jekyll directly so that redirects are
  handled properly.
- Document how deploy previews work.
- Document our production Netlify and DNS configuration.
- Start a short playbook for how to debug. It likely could be expanded,
  but this is a good first start.

Issue: #266
Signed-off-by: Mark Lodato <lodato@google.com>
Co-authored-by: Joshua Lock <joshuagloe@gmail.com>

docs/README.md

@@ -1,33 +1,56 @@
 # slsa.dev sources
 
-This directory contains sources for https://slsa.dev, served
-via GitHub pages and rendered with Jekyll.
+This directory contains sources for https://slsa.dev, rendered with Jekyll and
+served by [Netlify](https://netlify.com).
 
-## Developing and testing locally
+## Development
 
-1.  Install ruby, bundler, and the dev headers:
+### Building and testing locally
 
-    ```bash
-    apt install ruby ruby-dev bundler
-    ```
-
-    Alternatively, you can use `rbenv` to use the exact version of Ruby used by
-    GitHub Pages, but Debian's versions are likely close enough.
-
-2.  Clone this repo and change directory to `/docs`:
+1.  Clone this repo and change directory to `/docs`:
 
     ```bash
     git clone https://github.com/slsa-framework/slsa
     cd slsa/docs
     ```
 
-3.  Install the dependencies locally:
+2.  Install system dependencies:
+
+    -   Ruby, bundler, and the dev headers:
+
+        ```bash
+        apt install ruby ruby-dev bundler
+        ```
+
+        Alternatively, you can use `rbenv` to use the exact version of Ruby,
+        but Debian's versions are likely close enough.
+
+    -   Node and NPM:
+
+        ```bash
+        curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
+        nvm install 18
+        nvm use 18
+        ```
+
+        See https://github.com/nvm-sh/nvm for more instructions.
+
+    -   [Netlify CLI](https://docs.netlify.com/cli/get-started/):
+
+        ```bash
+        npm install -g netlify-cli
+        netlify login
+        ```
+
+3.  Install local dependencies:
 
     ```bash
     bundle config set --local path 'vendor/bundle'
     bundle install
     ```
 
+    You will need to re-run `bundle install` whenever the Gemfile.lock changes.
+
 4.  (optional) To enable `jekyll-github-metadata` to read metadata about the
     slsa repository from the GitHub API, create a GitHub
     [personal access token](https://github.com/settings/tokens/new) and add it
@@ -39,18 +62,75 @@ via GitHub pages and rendered with Jekyll.
         password 123abc-your-token
     ```
 
-5.  Run the project locally with `jekyll serve`:
+5.  Run the development server locally with
+    [Netlify CLI](https://github.com/netlify/cli/blob/main/docs/netlify-dev.md):
+
+    ```bash
+    netlify dev
+    ```
+
+    If you would like livereload (autorefresh page after every change) and/or
+    incremental builds (faster builds but possibly missing some changes), use:
 
     ```bash
-    bundle exec jekyll serve --livereload --incremental
+    netlify dev -c 'bundle exec jekyll serve --livereload --incremental'
     ```
 
-    The options can be omitted if preferred. `--livereload` causes the website
-    to autorefresh after every build. `--incremental` results in faster
-    incremental builds at the cost of possibly missing some changes.
+6.  Browse to http://localhost:8888 to view the site locally.
+
+### Deploy previews
+
+Netlify automatically builds and deploys previews of every pull request. Shortly
+after creating a PR, Netlify will add a comment with a link to a preview. The
+URL is of the form `https://deploy-preview-#--slsa.netlify.app` where `#` is the
+pull request number. This preview is updated on every push.
+
+## Production
+
+### Netlify configuration
+
+Site configuration: https://app.netlify.com/sites/slsa \
+Team configuration: https://app.netlify.com/teams/slsa
+
+Prefer to configure the site using `netlify.toml` rather than the web UI, when
+possible.
+
+To be added to ACL to allow you to configure the site, contact Mark Lodato or
+Joshua Lock via email or Slack. In the event that no SLSA team member has
+access, contact OpenSSF.
+
+### Production builds
+
+Netlify automatically builds and deploys the `main` branch to https://slsa.dev.
+
+### DNS
+
+OpenSSF (Linux Foundation) owns the DNS registration for slsa.dev and runs the
+DNS server. To request changes, email operations@openssf.org.
+
+It is configured to point to Netlify:
+
+```none
+slsa.dev      ALIAS  apex-loadbalancer.netlify.com
+www.slsa.dev  CNAME  slsa.netlify.app
+```
+
+## Playbooks
+
+### Something is wrong with the site. How do I debug and/or roll back?
+
+Go to https://app.netlify.com/sites/slsa/deploys?filter=main to see recent
+deployments. You need to be logged into Netlify to see the list of deployments,
+and in the "slsa" team to perform mutations (e.g. Publish).
+
+View a previous version of the site by clicking on a deployment's date:
+
+![screenshot of permalinks](../readme_images/netlify_permalinks_screenshot.png)
 
-6.  Browse to http://localhost:4000 to view the site locally.
+If you find that a previous version did not have the problem, you may roll back
+to that version by clicking on the row (not the date) and then **Publish
+deploy**.
 
-## Deployment
+![screenshot of rollback button](../readme_images/netlify_rollback_screenshot.png)
 
-Pushing to `main` will trigger a deployment of GitHub Pages.
+This will stay active until the next push to `main`.