toys-release 0.3.0 → 0.3.2

data/docs/guide.md

@@ -18,8 +18,6 @@ This user's guide covers all the features of Toys-Release in detail, including
 installation, normal operations, release pipeline customization, and a full
 configuration reference.
 
-**(This user's guide is still under construction.)**
-
 ## Conceptual overview
 
 Toys-Release is a comprehensive release pipeline system. It includes a set of
@@ -55,11 +53,11 @@ RubyGem, but does not require familiarity with Toys.
 
 Toys-Release must be installed into a GitHub repository. This involves:
 
-* Installing a Toys tool;
-* Writing a configuration file;
-* Defining a set of GitHub Actions workflows and a set of GitHub labels
-  (a tool is provided to perform this step); and
-* Providing necessary credentials.
+ *  Installing a Toys tool;
+ *  Writing a configuration file;
+ *  Defining a set of GitHub Actions workflows and a set of GitHub labels
+    (a tool is provided to perform this step); and
+ *  Providing necessary credentials.
 
 ### Prerequisites
 
@@ -178,25 +176,97 @@ and interact with the process.
 
 Overall, the process looks like this:
 
-1.  A maintainer schedules a release by triggering the "Open release request"
+1.  During development, commit messages for all commits should be formatted
+    according to the [Conventional Commits](https://conventionalcommits.org)
+    standard. This allows Toys-Release (and other similar tools) to interpret
+    the semantics of your changes and configure releases accordingly.
+
+2.  A maintainer schedules a release by triggering the "Open release request"
     GitHub Action. This action analyzes the repository, looking for changes in
     each component, deciding which components have releasable updates,
     determining the semver version bump for each, and building a changelog. It
     then opens a pull request with the version and changelog updates.
 
-2.  The maintainer can either merge the pull request (possibly with manual
+3.  The maintainer can either merge the pull request (possibly with manual
     modifications to the changelogs and/or version numbers to release) or close
     it unmerged.
 
-3.  If the pull request is merged, the release is automatically processed by
+4.  If the pull request is merged, the release is automatically processed by
     additional GitHub Actions. The automation verifies that the GitHub checks
     pass, and runs the release pipeline.
 
-4.  The results of the run are reported back to the release pull request. If
+5.  The results of the run are reported back to the release pull request. If
     the release failed, a GitHub issue is also automatically opened. A
     maintainer can retry a failed release by triggering the "Retry release"
     GitHub Action.
 
+### Commit message formatting
+
+When using Toys-Release, you should format all commit messages according to the
+[Conventional Commits](https://conventionalcommits.org) standard. This allows
+Toys-Release (and other similar tools) to interpret the semantics of your
+changes and configure releases accordingly. (Even if you are not using such
+tools, Conventional Commits encapsulates good best practice for writing useful
+commit messages.) Properly formatted conventional commit messages will
+determine what kind of version bump Toys-Release uses when releasing those
+changes, and the commit messages themselves will be used in the changelog that
+Toys-Release generates.
+
+Specifically, a change that adds a new feature, corresponding to a minor update
+under [Semantic Versioning](https://semver.org), should have a commit message
+tagged with `feat:`. For example:
+
+```
+feat: You can now upload a cat photo
+```
+
+A change that fixes a bug, corresponding to a patch change under Semver, should
+have a commit message tagged with `fix:`. For example:
+
+```
+fix: The app no longer crashes when a photo includes a dog instead of a cat
+```
+
+A change that updates documentation should have a commit message tagged with
+`docs:`. For example:
+
+```
+docs: Emphasize that photos should include cats rather than dogs
+```
+
+A breaking change, which would trigger a major update under Semver, can be
+expressed using either the `BREAKING CHANGE:` tag, or an exclamation mark after
+any other type of tag. Here are a few examples:
+
+```
+BREAKING CHANGE: Rename the "add-photo" API to "add-cat-photo"
+feat!: Raise an exception if a photo contains a dog instead of a cat
+```
+
+A change that does not actually make any functional change, such as a git
+repository configuration change, a CI change, or other admin-level change,
+should be tagged with `chore:`. For example:
+
+```
+chore: Attach a photo of a cat to the repo
+```
+
+Other common tags might include `refactor:`, `style:`, `test:`, and others. See
+https://conventionalcommits.org for more details and discussion.
+
+By default, Toys-Release specifically recognizes the `feat:`, `fix:`, and
+`docs:` tags, and uses them to configure releases and new versions. It also
+recognizes breaking changes. It considers other tags to be non-significant for
+release purposes. However, you can configure this behavior using the
+**commit_tags** configuration field. See the
+[configuration reference](#configuration-reference) for more details.
+
+It is legal to have multiple conventional commit formatted messages in a single
+commit message. Toys-Release will parse each commit message and use all
+properly formatted conventional commit messages it finds. In most cases,
+however, it is good practice to keep commits small and describable via a single
+conventional commit message.
+
 ### Requesting releases
 
 To request a release, navigate to the Actions tab in the GitHub UI, select the
@@ -216,12 +286,16 @@ appending the version to the component name, separated by a colon.
 For example, to request releases of the `toys` and `toys-release` components,
 you can enter the following text into "Components to release":
 
-    toys toys-release
+```sh
+toys toys-release
+```
 
 To make the above request but specifically request version 0.3.0 of the
 `toys-release` component:
 
-    toys toys-release:0.3.0
+```sh
+toys toys-release:0.3.0
+```
 
 ### Managing release pull requests
 
@@ -242,46 +316,256 @@ workflow will have the `release: pending` label applied. This label signals the
 release automation that this is a release pull request. If you remove this
 label, the automation will not process the release.
 
-Finally, you can even create a release pull request manually. You must simply
-ensure that:
+Finally, you can even create a release pull request manually, or using your own
+tools or processes. You must simply ensure that:
 
-* The pull request has the `release: pending` label applied
-* The pull request merges as a single commit (i.e. "squashed")
-* For each component you want to release, the version and changelog are
-  updated appropriately.
+ *  The pull request has the `release: pending` label applied
+ *  The pull request merges as a single commit (i.e. "squashed")
+ *  For each component you want to release, the version and changelog are
+    updated appropriately.
 
 If you close a release pull request without merging, the release will be
 canceled. The automation will apply the `release: aborted` label to indicate
 this.
 
-### Release results and logs
-
-(TODO)
+### Monitoring progress and results
+
+After a release pull request is merged, a GitHub Actions workflow will trigger
+and begin processing the release. You can follow the workflow logs if you want
+detailed information on the progress of the release. Additionally, updates will
+be posted to the pull request when the workflow begins and when it completes.
+These updates will include a link to the workflow logs for your convenience.
+
+After a workflow finishes, it will apply a label to the pull request indicating
+the final result. A successful release will have the `release: complete` label,
+while an unsuccessful release will have the `release: error` label. If an error
+occurred, the workflow will also open an issue in the repository reporting the
+failed release.
+
+Most of the useful workflow logs will appear in the "Process release request"
+job under the workflow. If you follow the logs, you will see the release goes
+through the following stages:
+
+ *  First, it publishes a comment to the pull request indicating that the
+    release is starting.
+ *  Second, it polls the GitHub checks for the merge commit. Toys-Release will
+    perform a release only if all required checks pass, so the release job will
+    wait for them to complete. If any checks fail, the release will fail.
+ *  Third, it runs a set of sanity checks, for example that it is looking at
+    the correct repository and commit, that there are no locally modified
+    files, and that the version numbers are set as expected.
+ *  Next, it runs the release pipeline itself. It first does an analysis of
+    which steps in the pipeline should run, then runs those steps in order.
+ *  Finally, it publishes a comment to the pull request reporting the final
+    result of the release.
 
 ### Troubleshooting and retrying releases
 
-(TODO)
+If a release fails, generally an issue will be opened in the repository, and
+the pull request will have the `release: error` label applied. Releases can
+fail for a number of reasons, including:
+
+ *  The GitHub checks for the commit representing the merge of the release pull
+    request, have failed or did not complete in a timely manner.
+ *  A failure during the release pipeline, such as an error during the build or
+    publication of a release artifact.
+ *  An intermittent failure of the release pipeline infrastructure, such as a
+    failure to obtain a VM to execute a GitHub Actions workflow.
+
+If a failure occurs, the release workflow may have published some basic
+information on the cause, to the release pull request. You can also find more
+detailed information in the release logs, a link to which should also have been
+published in the pull request comments. You should use this information to
+troubleshoot the release.
+
+In many cases, you can retry the release, possibly after doing something to
+address the cause. For example, if the release failed because of a flaky test
+in the GitHub checks, you can rerun the check, and once it passes, retry the
+release. Or, if the release failed because of expired RubyGems credentials, you
+can rotate the credentials (see [above](#provide-credentials)) and then retry
+the release.
+
+To retry a release, navigate to the Actions tab in the GitHub UI, select the
+"Retry release" workflow, and click the "Run workflow" dropdown. This will open
+a confirmation drop-down with a field for "Release PR number". Enter the number
+of the *release pull request* here, and then click the "Run workflow" button to
+retry the release.
+
+When a failure takes place, it is possible that the release partially completed
+but did not fully complete. For example, a GitHub release and tag may already
+have been created, but the gem was not successfully pushed to RubyGems. When
+you retry a release, the release script will automatically detect which release
+steps were already completed, and will skip them.
+
+If you need to "roll back" a failed release so it can be retried from a
+different commit, currently you must manually roll back the version number and
+changelog modification (i.e. roll back the changes in the release pull
+request). You might also need to remove an existing GitHub tag and release if
+they were already created.
+
+## Other features
 
 ### Documentation publication
 
-(TODO)
+One of the optional features of the release pipeline is publication of Yardoc
+reference documentation to GitHub Pages. This lets you host reference
+documentation for your Ruby gem on your GitHub Pages site, under github.io. As
+an example, of what this looks like you can see the reference documentation for
+the Toys gem at https://dazuma.github.io/toys/gems/toys.
+
+The features of this system are:
+
+ *  Host generated Yardoc (or rdoc) documentation for every version of the gem.
+ *  Host documentation for multiple gems per repository.
+ *  Permanent GitHub Pages (github.io) URL for each gem, which redirects to the
+    documentation for the latest version.
+ *  Automatically publish documentation with each release.
+
+#### Setting up documentation publication
+
+To set up documentation, do the following:
+
+ *  [Install the release tool](#install-the-release-tool) as documented in the
+    main setup procedure. This provides access to the Toys-Release command line.
+
+ *  Make sure you have a release config file. See the section on
+    [writing the configuration file](#write-the-configuration-file) for how to
+    get started here.
+
+ *  For each gem that you want documented, include the configuration setting
+    `gh_pages_enabled: true` in the component's configuration. Alternately, you
+    can set `gh_pages_enabled: true` at the top level of the configuration file
+    to enable documenting for all components.
 
-### Special commit tags
+ *  Create a starting gh-pages branch by running:
 
-(TODO)
+    ```sh
+    toys release gen-gh-pages
+    ```
+
+    This will generate the gh-pages branch and push some key files to it,
+    notably a `404.html` that does the redirecting to the latest documentation
+    version. This may clobber any other gh-pages that you have present.
+
+From this point on, any releases you do should also publish documentation to
+your page. To find the page, use the URL
+`https://<github-user>.github.io/<repo-name>/<component-name>`.
+
+If you add or otherwise change your components, you can rerun the
+`toys release gen-gh-pages` script to regenerate the files and update the
+redirects. This will not affect any actual documentation you may have generated
+previously.
+
+#### Special configuration
+
+There are a few configuration fields that affect documentation publication.
+
+ *  **gh_pages_directory** is the directory name for this component in the
+    documentation URL. This takes the place of the `<component-name>` in the
+    URL. For example, if you set `gh_pages_directory: foo/bar` for your
+    component, the documentation will be generated under the URL:
+    `https://<github-user>.github.io/<repo-name>/foo/bar`.
+
+    Note that if you modify this field after previously generating
+    documentation for some releases, you will need to manually move the
+    previous documentation into the new directory.
+
+ *  **gh_pages_version_var** is the name of the Javascript variable in the
+    `404.html` file that stores the latest version of this component's release.
+    You will generally not need to modify this unless the
+    automatically-generated variable name isn't unique for some reason.
+
+See the [component configuration](#component-configuration) section for more
+details.
+
+### Special commit messages
+
+Several special cases can be handled via commit tags that are defined by
+Toys-Release. These conventional commit messages can appear in a commit message
+and affect the behavior of that and other commits.
+
+ *  **semver-change:** This tag forces a certain semver change to apply to this
+    commit even if other commit tags say otherwise. For example, if a commit
+    describes a new feature, but you want it released as a patch version bump
+    rather than a minor version bump, you can include `semver-change: patch` in
+    the commit message. The full commit message might read thus:
+
+    ```
+    feat: Add a small button that doesn't do a lot
+    semver-change: patch
+    ```
+
+    Valid values for semver-change are `patch`, `minor`, `major`, and `none`.
+
+    The semver-change tag affects only the commit it is part of. If multiple
+    commits are included in a release, other commits in the release might still
+    upgrade the version bump to minor or higher.
+
+ *  **revert-commit:** This tag indicates that the commit reverts, and thus
+    nullifies the effect of, an earlier commit, thus removing any version bump
+    and any changelog entries that would otherwise have been generated. Use the
+    SHA of the earlier commit as the content of the tag. For example:
+
+    ```
+    revert-commit: b10c6fb3363bd1335dcfbd671bdceae53cd55716
+    ```
+
+    A commit can combine revert-commit with other conventional commit tags. It
+    can even include multiple revert-commit tags if the commit reverts more than
+    one previous commit.
 
 ### Running on the command line
 
-(TODO)
+The implementation of Toys-Release is done via Toys (i.e. command line) tools.
+In most cases, you will use the GitHub Actions integration to manage your
+releases, but you can also run the tools directly from the command line.
+
+To do so, first make sure you have
+[installed the release tool](#install-the-release-tool) as documented in the
+main setup procedure. Then, the command line tools will be available as
+subtools underneath `toys release`. For example, you could request a release
+from the command line instead of a GitHub Action, by running the command
+`toys release request`, and providing it the needed arguments and credentials.
+
+As with all Toys-based tools, you can pass `--help` to any tool to get detailed
+usage information. For example: `toys release request --help`. You can also run
+`toys release --help` for a list of all the release-related tools.
+
+The following are the available command line tools. You may recognize some of
+these as tools you used during the [installation](#installation) procedure.
+
+ *  **create-labels** Creates the GitHub labels used by the release system
+
+ *  **gen-config** Generates an initial release configuration file
+
+ *  **gen-gh-pages** Initializes the gh-pages branch for publishing
+    documentation
+
+ *  **gen-workflows** Generates the GitHub Actions workflows used by
+    Toys-Release
+
+ *  **perform** Runs the release pipeline from the command line. Assumes you
+    have already updated the version number and the changelog.
+
+ *  **request** Analyzes the repository history and opens a release pull
+    request including any pending releases. This is the command line tool used
+    by the "Open release request" GitHub Action.
+
+ *  **retry** Retries a failed release. This is the command line tool used by
+    the "Retry release" GitHub Action.
+
+There are also internal (hidden) subtools called "_onclosed" and "_onpush".
+These are the tools called by GitHub Actions automation in response to pull
+request events, and you should generally not call them directly.
 
 ## The release pipeline
 
 Toys-Release features a highly configurable build pipeline. By default it is
 configured to handle most RubyGems packages, and will:
 
-* Tag and post a GitHub Release
-* Build a RubyGems package and push it to rubygems.org
-* Optionally build Yardoc documentation and push it to GitHub Pages
+ *  Tag and post a GitHub Release
+ *  Build a RubyGems package and push it to rubygems.org
+ *  Optionally build Yardoc documentation and push it to GitHub Pages
 
 The pipeline system, however, lets you customize any aspect of the process, and
 even replace it with an entirely different process altogether, possibly even
@@ -292,23 +576,241 @@ configuration reference documentation.
 
 ### Pipeline steps
 
-(TODO)
+A release pipeline is defined as an ordered series of **steps**. Each of these
+steps may perform some task and/or exchange some data with other steps. For
+example, a step might install a bundle, another might build a gem package, and
+another might push a gem package built by a previous step to rubygems.org.
+
+The behavior of a step is determined by the **type** of the step, and by
+additional **configuration attributes** provided to the step. Each step also
+has a unique **name** that lets you identify it and connect it to other steps.
+
+When a pipeline is run, individual steps in the pipeline may or may not
+actually execute, depending on whether they are needed. For example, the step
+type that creates a GitHub release will always run if it is present in a
+pipeline, but the step type that installs the bundle will normally run only if
+another subsequent step *that will run* actually needs the bundle, and the step
+type that builds the gem package will normally run only if a subsequent step
+*that will run* actually uses the built package (e.g. to push it to RubyGems.)
+The decision of whether or not a step will run depends on the step's
+configuration, and the step dependencies configured into the pipeline.
+
+We will cover, as an example, the [standard pipeline](#the-standard-pipeline)
+for RubyGems releases below. First, however, we need to discuss how steps
+depend on one another and pass data around.
 
 ### Inter-step communication and dependencies
 
-(TODO)
+When a step runs, the working directory is set to the **component directory**
+in a *clean* checkout of the release SHA in the repository. Any changes it
+makes to the repository working directory are *not* preserved for other steps;
+instead, it must explicitly "output" any files it needs to make available, and
+other steps must explicitly access those files as "inputs". This is sometimes
+done by the step's code, but can also be specified in the step's configuration.
+
+For example, a step that builds a gem package should "output" the package so
+that it is available to other steps that want to publish it. This simply
+involves copying the relevant files to a special directory known as the output
+directory for that step (identified by step name). The standard **build_gem**
+step type does this in code. Alternatively, if you write a custom step that
+builds an artifact, you can specify, via the **outputs** configuration, the
+artifacts that you want made available. (See the
+[output config reference](#step-output-configuration) for details.)
+
+Then, a step can use a built artifact previously output by another step by
+copying it from the previous step's output directory. Again, this can be done
+in code, as by the standard **release_gem** step type. You can also specify,
+via the **inputs** configuration, artifacts to copy from another step's output
+into your working directory. (For details, see the
+[input config reference](#step-input-configuration).)
+
+When a step specifies the **inputs** configuration, any steps so referenced are
+also automatically tagged as *dependencies* of the step. If the pipeline
+determines the step should be run, then its dependencies are also marked as to
+be run.
+
+#### Inter-step communication example
+
+Consider the following simple, if contrived, pipeline:
+
+```yaml
+- name: create_file
+  type: command
+  command: ["touch", "my-file.txt"]
+  outputs:
+    - source_path: my-file.txt
+- name: create_another_file
+  type: command
+  command: ["touch", "another-file.txt"]
+  outputs:
+    - source_path: another-file.txt
+- name: show_file
+  type: command
+  command: ["cat", "my-file.txt"]
+  inputs:
+    - name: create_file
+      source_path: my-file.txt
+  run: true
+```
 
-### The standard pipeline
+This pipeline includes three steps. After each step, the git repository gets
+reset, so any files created by the step are not initially available to
+subsequent steps unless the step explicitly accesses them via inputs. Also note
+that all three steps are of type "command", which do not run by default unless
+something else causes them to run.
 
-(TODO)
+Let's consider these steps starting with the last one.
 
-### Custom steps
+The third step, named `show_file`, looks for a file `my-file.txt` in the
+*first* step's outputs, copies it into its working directory, and prints its
+contents to the logs. It includes the `run: true` configuration which forces it
+to run.
 
-(TODO)
+Because the third step, `show_file`, copies an input from the first step,
+`create_file`, the latter is a dependency of the former. And since the
+`show_file` is forced to run, then `create_file` will also run. This step will
+run first, because it is first in the list of steps, and it will create a file
+and copy it to its outputs so the `show_file` can access it.
 
-### Common pipeline modifications
+The second step, `create_another_file`, would create another file and copy it
+to its outputs. However, it neither is forced to run via `run: true` nor is
+listed as a dependency of any other step that will run. Therefore, the second
+step never runs at all.
 
-(TODO)
+### The standard pipeline
+
+The default release pipeline illustrates the above features of steps. It
+includes the following steps:
+
+ *  **bundle**: Installs the bundle, and copies the `Gemfile.lock` to its
+    output directory. This step runs because the later step **build_yard**
+    declares it as a dependency and accesses the `Gemfile.lock`.
+ *  **build_gem**: Builds the gem package, and copies the package file to its
+    output directory. This step runs because the later step **release_gem**
+    declares it as a dependency and accesses the built package.
+ *  **build_yard**: Builds the Yardoc documentation. By default, this step uses
+    the `yard` gem from the bundle, and thus depends on the earlier **bundle**
+    step. It copies the `Gemfile.lock` output by the earlier step. After
+    building the documentation into the `doc` directory, it copies that
+    directory to its output directory. This step runs *if* the later step
+    **push_gh_pages**, which lists it as a dependency, runs.
+ *  **release_github**: Pushes a release tag to GitHub and creates a GitHub
+    release. This step always runs and has no dependencies.
+ *  **release_gem**: Pushes the built gem package to rubygems.org. This step
+    lists the earlier **build_gem** step as a dependency, and copies the built
+    gem package from that step's output.
+ *  **push_gh_pages**: Pushes the built documentation to the `gh-pages` branch
+    so it shows up on the repository's GitHub Pages site. This step runs only
+    if the repository actually has a `gh-pages` branch and the release
+    configuration specifies that it should be pushed to. If this step does run,
+    it lists the earlier **build_yard** step as a dependency, and copies the
+    built documentation from that step's output.
+
+Ultimately, this pipeline will create a GitHub release, push a RubyGems
+package, and optionally push documentation.
+
+### Modifying the pipeline
+
+If your releases have different requirements, you can modify the release
+pipeline, by inserting steps, by modifying existing steps, or by replacing the
+entire pipeline with a new pipeline. These modifications can be made globally
+for all releases in a repository, or specifically for individual releasable
+components, by adding configuration at the top level of the configuration (see
+the [top level configuration reference](#top-level-configuration)) or
+underneath a particular component's configuration (see the
+[component configuration reference](#component-configuration)).
+
+ *  To insert new steps, at the beginning or end of the pipeline, or before or
+    after specific named steps, use the **append_steps** and **prepend_steps**
+    configurations.
+ *  To modify existing steps, use the **modify_steps** configuration. See the
+    reference on [build step modification](#build-step-modification).
+ *  There is no specific way to delete an existing step. This is because a step
+    might be referenced by other steps. To ensure a step does not run, you can
+    modify it to change its type to `noop` (which has no behavior and does not
+    run by default) and ensure that no step depends on it.
+ *  If your changes are more complex than can reasonably be expressed by
+    modifying the default pipeline, you can replace the pipeline completely
+    using the **steps** configuration.
+
+#### Pipeline modification example
+
+The `toys` gem itself has a customized release pipeline. This pipeline includes
+a step that merges key classes from `toys-core`, such as DSL classes, into the
+documentation for the `toys` gem.
+
+The merging is actually performed by a toys tool called `copy-core-docs`
+defined in the directory for the `toys` gem. The implementation itself isn't
+important; what's important is that we want this merging to be part of the
+release process.
+
+The `releases.yml` for the toys repository includes this configuration for the
+`toys` gem:
+
+```yaml
+components:
+  - name: toys
+    prepend_steps:
+      - name: copy_core_docs
+        type: tool
+        tool: [copy-core-docs]
+        outputs: [core-docs]
+    modify_steps:
+      - name: build_yard
+        inputs: [copy_core_docs]
+      - name: build_gem
+        inputs: [copy_core_docs]
+```
+
+Let's unpack what this is doing.
+
+First, we note that we are not replacing the default pipeline completely; we
+are only modifying it *for this one gem*. The other gems (`toys-core` and
+`toys-release`) continue to use the default pipeline unmodified.
+
+For the `toys` gem, then, we prepend one new step at the beginning of the
+pipeline. The step is named `copy_core_docs`, and it runs the toys tool that
+copies files (with some modifications to simplify them and make them suitable
+for just documentation) from `toys-core` into the `toys` directory under the
+`core-docs` subdirectory. This directory is not part of the include path, so
+these files are not in the require path and do not interfere with the
+functionality of the library. However, they are in the `.yardopts` file and are
+used when documentation is built. We then copy this new directory to the
+output for the `copy_core_docs` step, to preserve it for future steps.
+
+Next, we modify the `build_yard` step to load the `copy_core_docs` output. This
+brings those files back into our working directory when the Yardocs are built.
+It also adds the `copy_core_docs` step to the dependencies of `build_yard` to
+ensure it gets executed.
+
+We also modify the `build_gem` step to load the `copy_core_docs` output. This
+ensures that the files are also present when the gem is built, so that services
+like rubydoc.info will have them available when they build the documentation.
+Again, this also adds `copy_core_docs` to the dependencies of `build_gem`. As a
+dependency of both `build_gem` and `build_yard`, this ensures that our new step
+will indeed get executed. (It does not execute twice; Toys-Release ensures each
+step is executed at most once, even if it is listed multiple times as a
+dependency.)
+
+#### Useful types for custom steps
+
+The **command** and **tool** step types are both very useful when creating
+custom steps. We've seen in the [example above](#pipeline-modification-example)
+how a step of type **tool** is used in the customized release process for the
+`toys` gem itself. The **command** type is similar; it executes a Unix command
+rather than a Toys tool. These two types are very useful for performing
+arbitrary behavior during a release.
+
+Another step type that is occasionally useful is **noop**. This type has no
+behavior; it doesn't *do* anything, but you can configure it with inputs and
+outputs. This can be useful for consolidating data output by other steps. You
+can, for example, configure a **noop** with multiple **inputs** from other
+steps, configuring each input to copy to the noop's *output*. Now, all the
+files from potentially multiple inputs are combined and can be referenced
+conveniently via a single step's output.
+
+See the reference below on [build step types](#build-step-types) for detailed
+information on these and other step types and their configurations.
 
 ## Configuration reference
 
@@ -324,129 +826,137 @@ The top level of the yaml file is a dictionary that can include the following
 keys. Out of these, **repo**, **git_user_name**, and **git_user_email** are all
 required. The rest are optional.
 
-* **append_steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
-  A list of build steps to append to the end of the default build pipeline.
-  This can be used to modify the default build pipeline instead of redefining
-  the entire pipeline using the **steps** key.
-
-* **breaking_change_header**: *string* (optional) --
-  A changelog entry prefix that appears when a change is marked as breaking.
-  Default is `BREAKING CHANGE`.
-
-* **commit_tags**: *array of [CommitTagConfig](#commit-tag-configuration)* (optional) --
-  A set of configurations defining how to interpret
-  [conventional commit](https://conventionalcommits.org) tags, including how
-  they trigger releases, bump versions, and generate changelog entries. See
-  [commit tag configuration](#commit-tag-configuration) for details.
-  If not included, Toys-Release will use a default configuration as follows:
-
-      - tag: feat
-        semver: minor
-        header: ADDED
-      - tag: fix
-        semver: patch
-        header: FIXED
-      - tag: docs
-        semver: patch
-
-* **components**: *array of [ComponentConfig](#component-configuration)* (optional) --
-  An array of releasable components, usually RubyGems packages. See
-  [Component Configuration](#component-configuration) for details on the format
-  of each component. You can also use the name **gems** for this config key.
-
-* **coordinate_versions**: *boolean* (optional) --
-  If set to true, this is a shorthand for setting up a coordination group
-  containing all components in this repository. Defaults to *false*.
-
-* **coordination_groups**: *array of array of string* (optional) --
-  A list of disjoint sets of component names. Each set defines a group of
-  components that will always be released together with the same version
-  number. That is, if one or more components in a set are released, the entire
-  set is released, even components with no changes. This is useful for sets of
-  gems, such as the Rails gems, that are always released together.
-
-* **enable_release_automation**: *boolean* (optional) --
-  When enabled, the release pipeline runs automatically when a release pull
-  request is merged. Defaults to *true*.
-
-* **gh_pages_enabled**: *boolean* (optional) --
-  Whether to globally enable gh-pages publication for all releases. Defaults to
-  *false*.
-
-* **git_user_email**: *string* (required) --
-  The git `user.email` setting to use when making git commits.
-
-* **git_user_name**: *string* (required) --
-  The git `user.name` setting to use when making git commits.
-
-* **main_branch**: *string* (optional) --
-  The name of the main branch. Defaults to `main` if not provided.
-
-* **modify_steps**: *array of [BuildStepModification](#build-step-modification)* (optional) --
-  A set of modifications to the default build steps. This can be used to modify
-  the default build pipeline instead of redefining the entire pipeline using
-  the **steps** key.
-
-* **no_significant_updates_notice**: *string* (optional) --
-  A notice that appears in a changelog when a release is done but no other
-  changelog entries are present. Default is `No significant updates.`
-
-* **prepend_steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
-  A list of build steps to prepend to the start of the default build pipeline.
-  This can be used to modify the default build pipeline instead of redefining
-  the entire pipeline using the **steps** key.
-
-* **release_branch_prefix**: *string* (optional) --
-  The prefix for all release branch names. Defaults to `release`.
-
-* **release_aborted_label**: *string* (optional) --
-  The name of the GitHub issue label that identifies aborted release pull
-  requests. Defaults to `release: aborted`.
-
-* **release_complete_label**: *string* (optional) --
-  The name of the GitHub issue label that identifies successfully completed
-  release pull requests. Defaults to `release: complete`.
-
-* **release_error_label**: *string* (optional) --
-  The name of the GitHub issue label that identifies release pull requests in
-  an error state. Defaults to `release: error`.
-
-* **release_pending_label**: *string* (optional) --
-  The name of the GitHub issue label that identifies pending release pull
-  requests. Defaults to `release: pending`.
-
-* **repo**: *string* (required) --
-  The GitHub repository name in the form `owner/repo`. For example, the Toys
-  repo is `dazuma/toys`.
-
-* **required_checks**: *regexp/boolean* (optional) --
-  Identifies which GitHub checks must pass as a prerequisite for a release. If
-  a string is provided, it is interpreted as a Ruby regexp (PCRE) and
-  identifies the check names. A boolean value of *true* (the default) means all
-  checks must pass. A boolean value of *false* disables checking.
-
-* **required_checks_timeout**: *integer* (optional) --
-  The time to wait, in seconds, for required checks to pass during release
-  processing. Defaults to 900 (i.e. 15 minutes).
-
-* **signoff_commits**: *boolean* (optional) --
-  Whether to make commits with `--signoff`. Set this to true if your repository
-  has a policy that commits require signoff. Defaults to *false*.
-
-* **steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
-  The build pipeline as a list of build steps. See
-  [build step configuration](#build-step-configuration) for details on how to
-  define the pipeline. If this is not included, Toys-Release will use a default
-  pipeline as follows:
-
-      - name: bundle
-      - name: build_gem
-      - name: build_yard
-      - name: release_github
-      - name: release_gem
-        source: build_gem
-      - name: push_gh_pages
-        source: build_yard
+ *  **append_steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
+    A list of build steps to append to the end of the default build pipeline.
+    This can be used to modify the default build pipeline instead of redefining
+    the entire pipeline using the **steps** key.
+
+ *  **breaking_change_header**: *string* (optional) --
+    A changelog entry prefix that appears when a change is marked as breaking.
+    Default is `BREAKING CHANGE`.
+
+ *  **commit_tags**: *array of [CommitTagConfig](#commit-tag-configuration)* (optional) --
+    A set of configurations defining how to interpret
+    [conventional commit](https://conventionalcommits.org) tags, including how
+    they trigger releases, bump versions, and generate changelog entries. See
+    [commit tag configuration](#commit-tag-configuration) for details.
+    If not included, Toys-Release will use a default configuration as follows:
+
+    ```yaml
+    - tag: feat
+      semver: minor
+      header: ADDED
+    - tag: fix
+      semver: patch
+      header: FIXED
+    - tag: docs
+      semver: patch
+    ```
+
+ *  **components**: *array of [ComponentConfig](#component-configuration)* (optional) --
+    An array of releasable components, usually RubyGems packages. See
+    [Component Configuration](#component-configuration) for details on the
+    format of each component. You can also use the name **gems** for this
+    config key.
+
+ *  **coordinate_versions**: *boolean* (optional) --
+    If set to true, this is a shorthand for setting up a coordination group
+    containing all components in this repository. Defaults to *false*.
+
+ *  **coordination_groups**: *array of array of string* (optional) --
+    A list of disjoint sets of component names. Each set defines a group of
+    components that will always be released together with the same version
+    number. That is, if one or more components in a set are released, the
+    entire set is released, even components with no changes. This is useful for
+    sets of gems, such as the Rails gems, that are always released together.
+
+ *  **enable_release_automation**: *boolean* (optional) --
+    When enabled, the release pipeline runs automatically when a release pull
+    request is merged. Defaults to *true*.
+
+ *  **gh_pages_enabled**: *boolean* (optional) --
+    Whether to globally enable gh-pages publication for all releases. Defaults
+    to *false*.
+
+ *  **git_user_email**: *string* (required) --
+    The git `user.email` setting to use when making git commits.
+
+ *  **git_user_name**: *string* (required) --
+    The git `user.name` setting to use when making git commits.
+
+ *  **main_branch**: *string* (optional) --
+    The name of the main branch. Defaults to `main` if not provided.
+
+ *  **modify_steps**: *array of [BuildStepModification](#build-step-modification)* (optional) --
+    A set of modifications to the default build steps. This can be used to
+    modify the default build pipeline instead of redefining the entire pipeline
+    using the **steps** key.
+
+ *  **no_significant_updates_notice**: *string* (optional) --
+    A notice that appears in a changelog when a release is done but no other
+    changelog entries are present. Default is `No significant updates.`
+
+ *  **prepend_steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
+    A list of build steps to prepend to the start of the default build
+    pipeline. This can be used to modify the default build pipeline instead of
+    redefining the entire pipeline using the **steps** key.
+
+ *  **release_branch_prefix**: *string* (optional) --
+    The prefix for all release branch names. Defaults to `release`.
+
+ *  **release_aborted_label**: *string* (optional) --
+    The name of the GitHub issue label that identifies aborted release pull
+    requests. Defaults to `release: aborted`.
+
+ *  **release_complete_label**: *string* (optional) --
+    The name of the GitHub issue label that identifies successfully completed
+    release pull requests. Defaults to `release: complete`.
+
+ *  **release_error_label**: *string* (optional) --
+    The name of the GitHub issue label that identifies release pull requests in
+    an error state. Defaults to `release: error`.
+
+ *  **release_pending_label**: *string* (optional) --
+    The name of the GitHub issue label that identifies pending release pull
+    requests. Defaults to `release: pending`.
+
+ *  **repo**: *string* (required) --
+    The GitHub repository name in the form `owner/repo`. For example, the Toys
+    repo is `dazuma/toys`.
+
+ *  **required_checks**: *regexp/boolean* (optional) --
+    Identifies which GitHub checks must pass as a prerequisite for a release.
+    If a string is provided, it is interpreted as a Ruby regexp (PCRE) and
+    identifies the check names. A boolean value of *true* (the default) means
+    all checks must pass. A boolean value of *false* disables checking.
+
+ *  **required_checks_timeout**: *integer* (optional) --
+    The time to wait, in seconds, for required checks to pass during release
+    processing. Defaults to 900 (i.e. 15 minutes).
+
+ *  **signoff_commits**: *boolean* (optional) --
+    Whether to make commits with `--signoff`. Set this to true if your
+    repository has a policy that commits require signoff. Defaults to *false*.
+
+ *  **steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
+    The build pipeline as a list of build steps. See
+    [build step configuration](#build-step-configuration) for details on how to
+    define the pipeline. If this is not included, Toys-Release will use a
+    default pipeline as follows:
+
+    ```yaml
+    - name: bundle
+    - name: build_gem
+    - name: build_yard
+    - name: release_github
+    - name: release_gem
+      source: build_gem
+    - name: push_gh_pages
+      source: build_yard
+    ```
+
+    See the earlier section on [the standard pipeline](#the-standard-pipeline)
+    for a detailed description of the behavior of this default pipeline.
 
 ### Commit tag configuration
 
@@ -457,19 +967,19 @@ and how it should appear in the changelog. The format of the configuration is a
 dictionary with the keys documented here. The **tag** key is required; the
 remaining keys are optional and have defaults.
 
-* **header**: *string,null* (optional) --
-  A prefix that appears before each changelog entry generated by this tag. The
-  special value *null* suppresses changelog entry generation for this scope.
-  Defaults to the tag itself in all caps.
+ *  **header**: *string,null* (optional) --
+    A prefix that appears before each changelog entry generated by this tag.
+    The special value *null* suppresses changelog entry generation for this
+    scope. Defaults to the tag itself in all caps.
 
-* **scopes**: *array of [ScopeConfig](#scope-configuration)* (optional) --
-  Overrides for conventional commit scopes.
+ *  **scopes**: *array of [ScopeConfig](#scope-configuration)* (optional) --
+    Overrides for conventional commit scopes.
 
-* **semver**: *string* (optional) --
-  The semver version bump implied by changes of this type. Possible values are
-  `patch`, `minor`, `major`, and `none`. Default is `none`.
+ *  **semver**: *string* (optional) --
+    The semver version bump implied by changes of this type. Possible values
+    are `patch`, `minor`, `major`, and `none`. Default is `none`.
 
-* **tag**: *string* (required) -- The conventional commit tag.
+ *  **tag**: *string* (required) -- The conventional commit tag.
 
 #### Scope configuration
 
@@ -480,17 +990,17 @@ dependency-updating bots. Typically, `chore:` does not indicate a significant
 change that should trigger a release or appear in a changelog, but you might
 choose different behavior for dependency changes.
 
-* **header**: *string,null* (optional) --
-  A prefix that appears before each changelog entry generated by this tag. The
-  special value *null* suppresses changelog entry generation for this scope.
-  Defaults to the same setting used by the tag.
+ *  **header**: *string,null* (optional) --
+    A prefix that appears before each changelog entry generated by this tag.
+    The special value *null* suppresses changelog entry generation for this
+    scope. Defaults to the same setting used by the tag.
 
-* **scope**: *string* (required) -- The scope name.
+ *  **scope**: *string* (required) -- The scope name.
 
-* **semver**: *string* (optional) -- 
-  The semver version bump implied by changes of this type. Possible values are
-  `patch`, `minor`, `major`, and `none`. Defaults to the same setting used by
-  the tag.
+ *  **semver**: *string* (optional) -- 
+    The semver version bump implied by changes of this type. Possible values
+    are `patch`, `minor`, `major`, and `none`. Defaults to the same setting
+    used by the tag.
 
 ### Component configuration
 
@@ -498,87 +1008,90 @@ A component configuration specifies how a particular component (often a
 RubyGems package) should be released. Its format is a dictionary with the keys
 documented here.
 
-* **append_steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
-  A list of build steps to append to the end of this component's build
-  pipeline. This can be used to modify the build pipeline instead of redefining
-  the entire pipeline using the **steps** key.
-
-* **changelog_path**: *string* (optional) --
-  The path to the component's changelog file, relative to the component's
-  directory. Default is `CHANGELOG.md`.
-
-* **directory**: *string* (optional) --
-  The directory within the repository where this component is located. Defaults
-  to the component name, unless there is exactly one component in this
-  repository, in which case the default is the root of the repository, i.e.
-  "`.`". This directory is used to identify when files related to this
-  component have been changed, and is also used as a base directory for other
-  paths related to the component.
-
-* **exclude_globs**: *array of string* (optional) --
-  An array of globs identifying files or directories that should be ignored
-  when identifying changes to this component. These paths are relative to the
-  repo root.
-
-* **gh_pages_directory**: *string* (optional) --
-  The directory in the `gh-pages` branch under which this component's
-  documentation is published. The default is the component name.
-
-* **gh_pages_enabled**: *boolean* (optional) --
-  Whether gh-pages documentation publishing is enabled for this component.
-  Default is *true* if either **gh_pages_directory** or **gh_pages_version_var**
-  is set explicitly; otherwise *false*.
-
-* **gh_pages_version_var**: *string* (optional) --
-  The name of a Javascript variable within the `404.html` page under gh-pages
-  that identifies the latest release of this component. Defaults to a variable
-  name corresponding to the component name.
-
-* **include_globs**: *array of string* (optional) --
-  An array of globs identifying additional files or directories, not located in
-  the component's directory itself, that should signal changes to this
-  component. This can be used, for example, if the repo has global files shared
-  by multiple components, where a change in such a file should trigger releases
-  for all those components. These paths are relative to the repo root.
-
-* **modify_steps**: *array of [BuildStepModification](#build-step-modification)* (optional) --
-  A set of modifications to this component's build steps. This can be used to
-  modify the build pipeline instead of redefining the entire pipeline using
-  the **steps** key.
-
-* **name**: *string* (required) --
-  The name of the component, e.g. the name of the RubyGems package if this
-  component represents a gem.
-
-* **prepend_steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
-  A list of build steps to prepend to the start of this component's build
-  pipeline. This can be used to modify the build pipeline instead of redefining
-  the entire pipeline using the **steps** key.
-
-* **steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
-  A way to override the complete build pipeline for this component. If not
-  present, the default pipeline for the entire repository is used. (See the
-  **steps** key under [Top level configuration](#top-level-configuration).)
-
-* **version_constant**: *string* (optional) --
-  The fully-qualified name of the version constant. This is used to determine
-  the current version of the component. The default uses the module implied by
-  the component name. For example, if the component (gem) name is
-  `toys-release`, this defaults to `Toys::Release::VERSION`.
-
-* **version_rb_path**: *string* (optional) --
-  The path to a Ruby file that contains the current version of the component.
-  This file *must* include Ruby code that looks like this:
-
-      VERSION = "1.2.3"
+ *  **append_steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
+    A list of build steps to append to the end of this component's build
+    pipeline. This can be used to modify the build pipeline instead of
+    redefining the entire pipeline using the **steps** key.
+
+ *  **changelog_path**: *string* (optional) --
+    The path to the component's changelog file, relative to the component's
+    directory. Default is `CHANGELOG.md`.
+
+ *  **directory**: *string* (optional) --
+    The directory within the repository where this component is located.
+    Defaults to the component name, unless there is exactly one component in
+    this repository, in which case the default is the root of the repository,
+    i.e. "`.`". This directory is used to identify when files related to this
+    component have been changed, and is also used as a base directory for other
+    paths related to the component.
+
+ *  **exclude_globs**: *array of string* (optional) --
+    An array of globs identifying files or directories that should be ignored
+    when identifying changes to this component. These paths are relative to the
+    repo root.
+
+ *  **gh_pages_directory**: *string* (optional) --
+    The directory in the `gh-pages` branch under which this component's
+    documentation is published. The default is the component name.
+
+ *  **gh_pages_enabled**: *boolean* (optional) --
+    Whether gh-pages documentation publishing is enabled for this component.
+    Default is *true* if either **gh_pages_directory** or
+    **gh_pages_version_var** is set explicitly; otherwise *false*.
+
+ *  **gh_pages_version_var**: *string* (optional) --
+    The name of a Javascript variable within the `404.html` page under gh-pages
+    that identifies the latest release of this component. Defaults to an
+    auto-generated variable name corresponding to the component name.
+
+ *  **include_globs**: *array of string* (optional) --
+    An array of globs identifying additional files or directories, not located
+    in the component's directory itself, that should signal changes to this
+    component. This can be used, for example, if the repo has global files
+    shared by multiple components, where a change in such a file should trigger
+    releases for all those components. These paths are relative to the repo
+    root.
+
+ *  **modify_steps**: *array of [BuildStepModification](#build-step-modification)* (optional) --
+    A set of modifications to this component's build steps. This can be used to
+    modify the build pipeline instead of redefining the entire pipeline using
+    the **steps** key.
+
+ *  **name**: *string* (required) --
+    The name of the component, e.g. the name of the RubyGems package if this
+    component represents a gem.
+
+ *  **prepend_steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
+    A list of build steps to prepend to the start of this component's build
+    pipeline. This can be used to modify the build pipeline instead of
+    redefining the entire pipeline using the **steps** key.
+
+ *  **steps**: *array of [BuildStepConfig](#build-step-configuration)* (optional) --
+    A way to override the complete build pipeline for this component. If not
+    present, the default pipeline for the entire repository is used. (See the
+    **steps** key under [Top level configuration](#top-level-configuration).)
+
+ *  **version_constant**: *string* (optional) --
+    The fully-qualified name of the version constant. This is used to determine
+    the current version of the component. The default uses the module implied
+    by the component name. For example, if the component (gem) name is
+    `toys-release`, this defaults to `Toys::Release::VERSION`.
+
+ *  **version_rb_path**: *string* (optional) --
+    The path to a Ruby file that contains the current version of the component.
+    This file *must* include Ruby code that looks like this:
+
+    ```ruby
+    VERSION = "1.2.3"
+    ```
   
-  where the string is the latest released version. (Prior to the initial
-  release, this version should be `0.0.0`.) Typically, `VERSION` is a constant
-  defined in the "base module" for the Ruby library.
+    where the string is the latest released version. (Prior to the initial
+    release, this version should be `0.0.0`.) Typically, `VERSION` is a
+    constant defined in the "base module" for the Ruby library.
 
-  The default is `version.rb` within the lib path associated with the Ruby
-  module implied by the component name. For example, if the component (gem)
-  name is `toys-release`, this defaults to `lib/toys/release/version.rb`.
+    The default is `version.rb` within the lib path associated with the Ruby
+    module implied by the component name. For example, if the component (gem)
+    name is `toys-release`, this defaults to `lib/toys/release/version.rb`.
 
 ### Build step configuration
 
@@ -588,71 +1101,71 @@ define additional keys as documented under the section
 [build step types](#build-step-types). For more introductory information, see
 the section on [the release pipeline](#the-release-pipeline) above.
 
-* **name**: *string* (optional) --
-  The unique name of this build step in the build pipeline. If not explicitly
-  provided, a unique name will be generated.
+ *  **name**: *string* (optional) --
+    The unique name of this build step in the build pipeline. If not explicitly
+    provided, a unique name will be generated.
 
-* **type**: *string* (optional) --
-  The type of build step, defining what it does. Possible values are:
-  `build_gem`, `build_yard`, `bundle`, `command`, `noop`, `push_gh_pages`,
-  `release_gem`, `release_github`, and `tool`. For more information, see the
-  section [build step types](#build-step-types).
+ *  **type**: *string* (optional) --
+    The type of build step, defining what it does. Possible values are:
+    `build_gem`, `build_yard`, `bundle`, `command`, `noop`, `push_gh_pages`,
+    `release_gem`, `release_github`, and `tool`. For more information, see the
+    section [build step types](#build-step-types).
 
-* **run**: *boolean* (optional) --
-  Whether to force this step to run. Typically, build steps will run only if
-  the build type determines that it should run, or if the step is a dependency
-  of another step that will run. You can, however, force a step to run that
-  would otherwise not do so by setting this key to *true*.
+ *  **run**: *boolean* (optional) --
+    Whether to force this step to run. Typically, build steps will run only if
+    the build type determines that it should run, or if the step is a
+    dependency of another step that will run. You can, however, force a step to
+    run that would otherwise not do so by setting this key to *true*.
 
-* **inputs**: *array of [InputConfig](#step-input-configuration)* (optional) --
-  Inputs to this step, indicating dependencies on other steps and files to copy
-  from those steps' outputs.
+ *  **inputs**: *array of [InputConfig](#step-input-configuration)* (optional) --
+    Inputs to this step, indicating dependencies on other steps and files to
+    copy from those steps' outputs.
 
-* **outputs**: *array of [OutputConfig](#step-output-configuration)* (optional) --
-  Files to copy to this step's output so they become available to other steps.
+ *  **outputs**: *array of [OutputConfig](#step-output-configuration)* (optional) --
+    Files to copy to this step's output so they become available to other steps.
 
 #### Step input configuration
 
-A step input represents a dependency on another step: if this step is run, the
-other step will also be run. It also describes files that should be copied from
-the dependent step's output and made available to the depending step. This
-configuration is a dictionary supporting the following keys:
-
-* **collisions**: *string* (optional) --
-  A symbolic value indicating what to do if a collision occurs between incoming
-  and existing files. Possible values are:
-
-    * `error`: (the default) Abort with an error
-    * `keep`: Keep the existing file
-    * `replace`: Replace the existing file with the incoming file
-
-* **dest**: *string or false* (optional) --
-  A symbolic value indicating where to copy the dependent step's output to.
-  Possible values are:
-
-    * `component`: (the default) Copy files to the component directory
-    * `repo_root`: Copy files to the repository root
-    * `output`: Copy files to this step's output directory
-    * `temp`: Copy files to this step's temp directory
-    * `none`: Do not copy any files, but just declare a dependency
-
-* **dest_path**: *string* (optional) --
-  The path in the destination to copy to. If **source_path** is provided,
-  **dest_path** is the corresponding path in the destination. If **source_path**
-  is not provided, **dest_path** is a directory into which the source contents
-  are copied. If **dest_path** is not provided, it defaults to the effective
-  value of **source_path**, i.e. things are copied into the same locations
-  within the destination as they were in the source.
-
-* **name**: *string* (required) --
-  The name of the step to depend on. The dependent step must be located earlier
-  in the pipeline than the depending step.
-
-* **source_path**: *string* (optional) --
-  The path of the file or directory to copy from the source output. Only this
-  item (recursively, if a directory) is copied. If this key is not provided,
-  *all* contents of the source output are copied (e.g. the default is
-  effectively "`.`")
+A step input represents a dependency on another step: if this (depending) step
+is run, that other (dependent) step will also be run. It also describes files
+that should be copied from the dependent step's output and made available to
+the depending step. This configuration is a dictionary with the following keys:
+
+ *  **collisions**: *string* (optional) --
+    A symbolic value indicating what to do if a collision occurs between
+    incoming and existing files. Possible values are:
+
+     *  `error`: (the default) Abort with an error
+     *  `keep`: Keep the existing file
+     *  `replace`: Replace the existing file with the incoming file
+
+ *  **dest**: *string or false* (optional) --
+    A symbolic value indicating where to copy the dependent step's output to.
+    Possible values are:
+
+     *  `component`: (the default) Copy files to the component directory
+     *  `repo_root`: Copy files to the repository root
+     *  `output`: Copy files to this step's output directory
+     *  `temp`: Copy files to this step's temp directory
+     *  `none`: Do not copy any files, but just declare a dependency
+
+ *  **dest_path**: *string* (optional) --
+    The path in the destination to copy to. If **source_path** is provided,
+    **dest_path** is the corresponding path in the destination. If
+    **source_path** is not provided, **dest_path** is a directory into which
+    the source contents are copied. If **dest_path** is not provided, it
+    defaults to the effective value of **source_path**, i.e. things are copied
+    into the same locations within the destination as they were in the source.
+
+ *  **name**: *string* (required) --
+    The name of the step to depend on. The dependent step must be located
+    earlier in the pipeline than the depending step.
+
+ *  **source_path**: *string* (optional) --
+    The path of the file or directory to copy from the source output. Only this
+    item (recursively, if a directory) is copied. If this key is not provided,
+    *all* contents of the source output are copied (e.g. the default is
+    effectively "`.`")
 
 #### Step output configuration
 
@@ -660,155 +1173,157 @@ A step output represents files automatically copied to the step's output
 directory after the step runs. This configuration is a dictionary supporting
 the following keys:
 
-* **collisions**: *string* (optional) --
-  A symbolic value indicating what to do if a collision occurs between incoming
-  and existing files. Possible values are:
+ *  **collisions**: *string* (optional) --
+    A symbolic value indicating what to do if a collision occurs between incoming
+    and existing files. Possible values are:
 
-    * `error`: (the default) Abort with an error
-    * `keep`: Keep the existing file
-    * `replace`: Replace the existing file with the incoming file
+     *  `error`: (the default) Abort with an error
+     *  `keep`: Keep the existing file
+     *  `replace`: Replace the existing file with the incoming file
 
-* **dest_path**: *string* (optional) --
-  The path in the output directory to copy to. If **source_path** is provided,
-  **dest_path** is the corresponding path in the output. If **source_path** is
-  not provided, **dest_path** is a directory into which the source contents are
-  copied. If **dest_path** is not provided, it defaults to the effective value
-  of **source_path**, i.e. things are copied into the same locations within the
-  output as they were in the source.
+ *  **dest_path**: *string* (optional) --
+    The path in the output directory to copy to. If **source_path** is
+    provided, **dest_path** is the corresponding path in the output. If
+    **source_path** is not provided, **dest_path** is a directory into which
+    the source contents are copied. If **dest_path** is not provided, it
+    defaults to the effective value of **source_path**, i.e. things are copied
+    into the same locations within the output as they were in the source.
 
-* **source**: *string* (optional) --
-  A symbolic value indicating where to copy from. Possible values are:
+ *  **source**: *string* (optional) --
+    A symbolic value indicating where to copy from. Possible values are:
 
-    * `component`: (the default) Copy files from the component directory
-    * `repo_root`: Copy files from the repository root
-    * `temp`: Copy files from this step's temp directory
+     *  `component`: (the default) Copy files from the component directory
+     *  `repo_root`: Copy files from the repository root
+     *  `temp`: Copy files from this step's temp directory
 
-* **source_path**: *string* (optional) --
-  The path of the file or directory to copy from the source. Only this item
-  (recursively, if a directory) is copied. If this key is not provided, *all*
-  contents of the source are copied (e.g. the default is effectively "`.`")
+ *  **source_path**: *string* (optional) --
+    The path of the file or directory to copy from the source. Only this item
+    (recursively, if a directory) is copied. If this key is not provided, *all*
+    contents of the source are copied (e.g. the default is effectively "`.`")
 
 #### Build step types
 
 This is a list of the available build step types, including their behavior and
 any additional configuration keys supported by each.
 
-* **build_gem** -- A step that builds a gem package.
+ *  **build_gem** -- A step that builds a gem package.
 
-  This step builds the gem described by the properly named gemspec file for
-  this component. The built package file is copied to this step's output. Other
-  steps (such as **release_gem**) can declare it as an input to get access to
-  the built package. This step does not run unless it is so declared as a
-  dependency or unless it is requested explicitly.
+    This step builds the gem described by the properly named gemspec file for
+    this component. The built package file is copied to this step's output.
+    Other steps (such as **release_gem**) can declare it as an input to get
+    access to the built package. This step does not run unless it is declared
+    as an input dependency, or unless it is requested explicitly using the
+    **run** configuration.
 
-* **build_yard** -- A step that builds Yardocs.
+ *  **build_yard** -- A step that builds Yardocs.
 
-  This step builds documentation using [YARD](https://yardoc.org). The built
-  documentation is copied to this step's output in the directory `doc/`. Other
-  steps (such as **push_gh_pages**) can declare it as an input to get access to
-  the built documentation. This step does not run unless it is so declared as a
-  dependency or unless it is requested explicitly.
+    This step builds documentation using [YARD](https://yardoc.org). The built
+    documentation is copied to this step's output in the directory `doc/`.
+    Other steps (such as **push_gh_pages**) can declare it as an input to get
+    access to the built documentation. This step does not run unless it is
+    declared as an input dependency, or unless it is requested explicitly using
+    the **run** configuration.
 
-  This step supports the following additional configuration keys:
+    This step supports the following additional configuration keys:
 
-    * **bundle_step**: *string* (optional) --
-      The name of the bundle step. Defaults to `bundle`. This is used if the
-      **uses_gems** key is *not* provided.
+     *  **bundle_step**: *string* (optional) --
+        The name of the bundle step. Defaults to `bundle`. This is used if the
+        **uses_gems** key is *not* provided.
 
-    * **uses_gems**: *array of (string or array of string)* (optional) --
-      An array of gem specifications, each of which can be a simple gem name or
-      an array including rubygems-style version requirements. These gems are
-      provided to Yard, and can include gems such as `redcarpet` that may be
-      needed for markup handling. If this key is included, the specified gems
-      are installed directly; if not, the bundle step is declared as a
-      dependency instead.
+     *  **uses_gems**: *array of (string or array of string)* (optional) --
+        An array of gem specifications, each of which can be a simple gem name
+        or an array including rubygems-style version requirements. These gems
+        are provided to Yard, and can include gems such as `redcarpet` that may
+        be needed for markup handling. If this key is included, the specified
+        gems are installed directly; if not, the bundle step is declared as a
+        dependency instead.
 
-* **bundle** -- A step that installs the bundle in the component directory.
+ *  **bundle** -- A step that installs the bundle in the component directory.
 
-  This step copies the resulting `Gemfile.lock` to its output. Other steps can
-  declare it as an input to get access to the `Gemfile.lock`. This step
-  does not run unless it is so declared as a dependency or unless it is
-  requested explicitly.
+    This step copies the resulting `Gemfile.lock` to its output. Other steps
+    can declare it as an input to get access to the `Gemfile.lock`. This step
+    does not run unless it is declared as an input dependency, or unless it is
+    requested explicitly using the **run** configuration.
 
-  This step supports the following additional configuration keys:
+    This step supports the following additional configuration keys:
 
-    * **chdir**: *string* (optional) --
-      Change to the specified directory (relative to the component directory)
-      when installing the bundle. By default, runs in the component directory.
+     *  **chdir**: *string* (optional) --
+        Change to the specified directory (relative to the component directory)
+        when installing the bundle. Defaults to component directory.
 
-* **command** -- A step that runs a command in the component directory.
+ *  **command** -- A step that runs a command in the component directory.
 
-  This step supports the following additional configuration keys:
+    This step supports the following additional configuration keys:
 
-    * **chdir**: *string* (optional) --
-      Change to the specified directory (relative to the component directory)
-      when running the command. By default, runs in the component directory.
+     *  **chdir**: *string* (optional) --
+        Change to the specified directory (relative to the component directory)
+        when running the command. Defaults to component directory.
 
-    * **command**: *array of string* (required) --
-      The command to run
+     *  **command**: *array of string* (required) --
+        The command to run
 
-    * **continue_on_error**: *boolean* (optional) --
-      If *true*, continue to run the pipeline if the command exits abnormally.
-      If *false* (the default), the pipeline aborts.
+     *  **continue_on_error**: *boolean* (optional) --
+        If *true*, continue to run the pipeline if the command exits
+        abnormally. If *false* (the default), the pipeline aborts.
 
-  This step does not run unless it is requested explicitly using the **run**
-  configuration or it is declared as a dependency.
+    This step does not run unless it is requested explicitly using the **run**
+    configuration, or it is declared as a dependency.
 
-* **noop** -- A no-op step that does nothing. This type is usually configured
-  with inputs and outputs and is used to collect or consolidate data from other
-  steps.
+ *  **noop** -- A no-op step that does nothing. This type is usually configured
+    with inputs and outputs and is used to collect or consolidate data from
+    other steps.
 
-  This step does not run unless it is requested explicitly using the **run**
-  configuration or it is declared as a dependency.
+    This step does not run unless it is requested explicitly using the **run**
+    configuration, or it is declared as a dependency.
 
-* **push_gh_pages** -- A step that pushes documentation to the gh-pages branch.
+ *  **push_gh_pages** -- A step that pushes documentation to the gh-pages branch.
 
-  The documentation to publish should be under `doc/` in the output directory
-  of a "source" step, normally the **build_yard** step. This source step is
-  automatically declared as a dependency.
+    The documentation to publish should be under `doc/` in the output directory
+    of a "source" step, normally the **build_yard** step. This source step is
+    automatically declared as a dependency.
 
-  This step supports the following additional configuration keys:
+    This step supports the following additional configuration keys:
 
-    * **source**: *string* (optional) --
-      The name of the source step. Defaults to `build_yard`.
+     *  **source**: *string* (optional) --
+        The name of the source step. Defaults to `build_yard`.
 
-  This step runs if gh-pages publishing is enabled in the component.
+    This step runs if gh-pages publishing is enabled for the component.
 
-* **release_gem** -- A step that pushes a gem package to rubygems.org.
+ *  **release_gem** -- A step that pushes a gem package to rubygems.org.
 
-  The package must be provided under `pkg/` in the output directory of a
-  "source" step, normally the **build_gem** step. This source step is
-  automatically declared as a dependency.
+    The package must be provided under `pkg/` in the output directory of a
+    "source" step, normally the **build_gem** step. This source step is
+    automatically declared as a dependency.
 
-  This step supports the following additional configuration keys:
+    This step supports the following additional configuration keys:
 
-    * **source**: *string* (optional) --
-      The name of the source step. Defaults to `build_gem`.
+     *  **source**: *string* (optional) --
+        The name of the source step. Defaults to `build_gem`.
 
-  This step runs if a correctly-named gemspec file is present in the component
-  directory.
+    This step runs if a correctly-named gemspec file is present in the component
+    directory.
 
-* **release_github** -- A step that creates a git tag and GitHub release.
+ *  **release_github** -- A step that creates a git tag and GitHub release.
 
-  This step always runs if present in the pipeline.
+    This step always runs if present in the pipeline.
 
-* **tool** -- A step that runs a Toys tool in the component directory.
+ *  **tool** -- A step that runs a Toys tool in the component directory.
 
-  This step supports the following additional configuration keys:
+    This step supports the following additional configuration keys:
 
-    * **chdir**: *string* (optional) --
-      Change to the specified directory (relative to the component directory)
-      when running the tool. By default, runs in the component directory.
+     *  **chdir**: *string* (optional) --
+        Change to the specified directory (relative to the component directory)
+        when running the tool. Defaults to component directory.
 
-    * **continue_on_error**: *boolean* (optional) --
-      If *true*, continue to run the pipeline if the tool exits abnormally. If
-      *false* (the default), the pipeline aborts.
+     *  **continue_on_error**: *boolean* (optional) --
+        If *true*, continue to run the pipeline if the tool exits abnormally.
+        If *false* (the default), the pipeline aborts.
 
-    * **tool**: *array of string* (required) --
-      The tool to run
+     *  **tool**: *array of string* (required) --
+        The tool to run
 
-  This step does not run unless it is requested explicitly using the **run**
-  configuration or it is declared as a dependency.
+    This step does not run unless it is requested explicitly using the **run**
+    configuration, or it is declared as a dependency.
 
 #### Build step modification
 
@@ -819,11 +1334,11 @@ below.
 The **name** and **type** fields filter the steps to modify. If neither is
 provided, *all* steps are modified.
 
-* **name**: *string* (optional) --
-  Modify only the step with this unique name.
+ *  **name**: *string* (optional) --
+    Modify only the step with this unique name.
 
-* **type**: *string* (optional) --
-  Modify only steps matching this type.
+ *  **type**: *string* (optional) --
+    Modify only steps matching this type.
 
 All other keys represent changes to the configuration of matching steps. You
 can provide either the *null* value to delete the key, or a new full value for