From c8604ad2b590d4d8467d5d7c4d0e7b94aaf3e145 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Misty=20De=20M=C3=A9o?= <misty@axo.dev>
Date: Wed, 20 Sep 2023 16:50:40 -0700
Subject: [PATCH] docs: document new CI features

This begins a new section in the documentation with the new features
from CI++, including PR release builds and custom publish jobs.
---
 book/src/SUMMARY.md        |  1 +
 book/src/customizing-ci.md | 63 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)
 create mode 100644 book/src/customizing-ci.md

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index b73eb25d4..b12d52569 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -7,6 +7,7 @@
   - [A Simple Application](./simple-guide.md)
   - [More Complex Workspaces](./workspace-guide.md)
   - [Using cargo-release](./cargo-release-guide.md)
+- [Customizing CI](./customizing-ci.md)
 - [Reference](./reference.md)
   - [Concepts](./concepts.md)
   - [Config](./config.md)
diff --git a/book/src/customizing-ci.md b/book/src/customizing-ci.md
new file mode 100644
index 000000000..37535b4ce
--- /dev/null
+++ b/book/src/customizing-ci.md
@@ -0,0 +1,63 @@
+# Customizing CI
+
+Out of the box, cargo-dist's CI configuration is designed to cover the majority of usecases. We provide some tools to customize how it works for your project.
+
+## Build and upload artifacts on every pull request
+
+> since 0.3.0
+
+By default, cargo-dist will run the plan step on every pull request but won't perform a full release build. If these builds are turned on, the resulting pull request artifacts won't be uploaded to a release but will be available as a download from within the CI job. To enable this, select the "upload" option from the "check your release process in pull requests" question in `cargo-dist-init` or set the `pr-run-mode` key to `"upload"` in `Cargo.toml`. For example:
+
+```toml
+pr-run-mode = "upload"
+```
+
+## Custom jobs
+
+> since 0.3.0
+
+cargo-dist's CI can be configured to call additional jobs on top of the ones it has builtin. Currently, we support adding extra jobs to the publish step; in the future, we'll allow extending all of the lifecycle steps of the CI workflow. To add one, you need to follow two steps:
+
+1. Define the new job as a reusable workflow using the standard method defined by your CI system. For GitHub actions, see the documentation on [reusable workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows#creating-a-reusable-workflow).
+2. Add the name of your new workflow file to the `publish-jobs` array in your `Cargo.toml`, prefixed with a `./`. For example, if your job name is `.github/workflows/my-publish.yml`, you would write it like this:
+
+```toml
+publish-jobs = ["./my-publish"]
+```
+
+Here's an example reusable workflow written using GitHub Actions. It won't do any real publishing, just echo text to the CI output. First, create a file named `.github/workflows/publish-greeter.yml` with these contents:
+
+```yaml
+name: Greeter
+
+on:
+  # Defining workflow_call means that this workflow can be called from
+  # your main workflow job
+  workflow_call:
+    # cargo-dist exposes the plan from the plan step, as a JSON string,
+    # to your job if it needs it
+    inputs:
+      plan:
+        required: true
+        type: string
+
+jobs:
+  greeter:
+    runs-on: ubuntu-latest
+    # This is optional; it exposes the plan to your job as an environment variable
+    env:
+      PLAN: ${{ inputs.plan }}
+    steps:
+      - name: Step 1
+        run: |
+          echo "Hello!"
+          echo "Plan is: ${PLAN}"
+```
+
+Then, add the following to your `publish-jobs` array:
+
+```toml
+publish-jobs = ["./publish-greeter"]
+```
+
+Running `cargo-dist init` for your tool will update your GitHub Actions configuration to make use of the new reusable workflow during the publish step.