Documentation: start writing v4-specific docs

Signed-off-by: Hank Donnay <[email protected]>

.github/workflows/cut-release.yml

@@ -9,12 +9,17 @@ on:
 name: Upload Release Assets
 
 jobs:
-  build:
-    name: Upload Release Assets
+  checkout:
+    name: Checkout Code
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Code
         uses: actions/checkout@v2
+  build:
+    name: Upload Release Assets
+    runs-on: ubuntu-latest
+    needs: checkout
+    steps:
       - name: Prepare Environment
         run: |
           : "${tag:=${GITHUB_REF#refs/tags/}}"
@@ -50,3 +55,22 @@ jobs:
         run: |
           docker login -u "${QUAY_USER}" -p '${{ secrets.QUAY_TOKEN }}' quay.io
           docker push "${TAG}"
+  deploy-documentation:
+    name: Deploy Documentation
+    runs-on: ubuntu-latest
+    needs: checkout
+    steps:
+      - name: Setup
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: 'latest'
+      - name: Build
+        run: mdbook build --dest-dir "./book/${GITHUB_REF#refs/tags/}"
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book
+          keepFiles: true

.github/workflows/documentation.yml

@@ -0,0 +1,31 @@
+---
+name: Deploy Master Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - development-4.0  # Remove this when the branch switch happens.
+    paths:
+      - 'Documentation/**'
+
+jobs:
+  deploy-documentation:
+    name: Deploy Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Setup
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: 'latest'
+      - run: mdbook build
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book
+          keepFiles: true

.gitignore

@@ -1 +1,2 @@
 vendor/
+book/

Documentation/SUMMARY.md

@@ -0,0 +1,6 @@
+# Summary
+
+- [Operation](./TODO.md)
+- [API](./TODO.md)
+- [Contribution](./TODO.md)
+  - [Releases](./contribution/releases.md)

Documentation/TODO.md

@@ -0,0 +1 @@
+# Contribution

Documentation/contribution/releases.md

@@ -0,0 +1,49 @@
+# Releases
+
+Clair releases are cut roughly every three months and actively maintained for
+six.
+
+This means that bugfixes should be landed on `master` (if applicable) and then
+marked for backporting to a minor version's release branch. The process for
+doing this is not yet formalized.
+
+## Process
+
+### Minor
+
+When cutting a new minor release, two things need to be done: creating a tag and
+creating a release branch. This can be done like so:
+
+```sh
+git tag -as v4.x.0 HEAD
+git push upstream HEAD:release-4.x tag v4.x.0
+```
+
+Then, a "release" needs to be created in the Github UI using the created tag.
+
+### Patch
+
+A patch release is just like a minor release with the caveat that minor version
+tags should *only* appear on release branches and a new branch does not need to
+be created.
+
+```sh
+git checkout release-4.x
+git tag -as v4.x.1 HEAD
+git push upstream tag v4.x.1
+```
+
+Then, a "release" needs to be created in the Github UI using the created tag.
+
+### Creating Artifacts
+
+Clair's artifact release process is automated and driven off the releases in
+Github.
+
+Publishing a new release in the Github UI automatically triggers the creation of
+a complete source archive and a container. The archive is attached to the
+release, and the container is pushed to the
+[`quay.io/projectquay/clair`](https://quay.io/repository/projectquay/clair)
+repository.
+
+This is all powered by a Github Action in `.github/workflows/cut-release.yml`.

book.toml

@@ -0,0 +1,14 @@
+[book]
+title = "Clair Documentation"
+authors = ["Clair Authors"]
+description = "Documentation for Clair."
+src = "Documentation"
+language = "en"
+
+[build]
+build-dir = "book"
+create-missing = true
+
+[output.html]
+git-repository-url= "https://github.com/quay/clair"
+preferred-dark-theme = "coal"