toys-release 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e246a109a9bcbbe565935d1cf5a915308c4e0cb52185d916050cc9f921f23902
-  data.tar.gz: 581130fc95c1cfe9bf04122e89d94b1b4559eeb8cd392f87a561c910be183c99
+  metadata.gz: 2a2ec831144ec904f29bedffdc558c426447b4d0fe28f960dff189689f02ca03
+  data.tar.gz: 2ce6d38ede95e613c883f32df9d4592ba6228af96a8da9128da1eae0e760134e
 SHA512:
-  metadata.gz: c81089d76c5038be6a72440228e94bfc5fec13f9943a5487e5076849f62e38eb8ceda2ed504719103d6a45315c12da1872079bf098c5231d88f8a61085339b28
-  data.tar.gz: a1c0b68d7152331c1a7734f2e81f75f367ebb9fc7035c30de8c1189b66823e060fc1ce97085bdd389a68cbdcffb7aaf1955beba9f440dff95abd9eaa9640335c
+  metadata.gz: 5dddfaa0f0b174b388d1c7c37271f69e2ae6ee79b2f80d641e36760339ce0881e61ee831095b40ee647455d9013287ec89f6f362f641eaff3526715d71467a07
+  data.tar.gz: db8463f7cacbac2eda9f904d481bcfcbecca7221e9584918708511ef0ee6dc10d46d2921ae978195b9bec8af0de1e8ed26db1495373c9007558916994e25aa5c

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release History
 
+### v0.3.1 / 2025-12-22
+
+* FIXED: Reset the local repository prior to each pipeline step
+* DOCS: Updates to readmes and users guides
+
 ### v0.3.0 / 2025-12-06
 
 This release includes fairly substantial changes, a few of them breaking, to the configuration mechanism:

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
@@ -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
@@ -242,8 +312,8 @@ 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")
@@ -254,25 +324,227 @@ 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.
+
+* Create a starting gh-pages branch by running:
+
+      toys release gen-gh-pages
 
-### Special commit tags
+  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.
 
-(TODO)
+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
 
@@ -292,23 +564,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
 
@@ -448,6 +938,9 @@ required. The rest are optional.
       - 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
 
 A commit tag configuration specifies how the release system should handle a
@@ -613,10 +1106,10 @@ the section on [the release pipeline](#the-release-pipeline) above.
 
 #### 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:
+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
@@ -698,16 +1191,18 @@ any additional configuration keys supported by each.
   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.
+  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.
 
   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.
+  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:
 
@@ -727,8 +1222,8 @@ any additional configuration keys supported by each.
 
   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.
+  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:
 
@@ -752,14 +1247,14 @@ any additional configuration keys supported by each.
       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.
+  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.
 
   This step does not run unless it is requested explicitly using the **run**
-  configuration or it is declared as a dependency.
+  configuration, or it is declared as a dependency.
 
 * **push_gh_pages** -- A step that pushes documentation to the gh-pages branch.
 
@@ -808,7 +1303,7 @@ any additional configuration keys supported by each.
       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.
+  configuration, or it is declared as a dependency.
 
 #### Build step modification
 

data/lib/toys/release/version.rb

@@ -6,6 +6,6 @@ module Toys
     # Current version of the Toys release system.
     # @return [String]
     #
-    VERSION = "0.3.0"
+    VERSION = "0.3.1"
   end
 end

data/toys/.lib/toys/release/pipeline.rb

@@ -471,6 +471,7 @@ module Toys
         @utils.log("Pre-cleaning the repo for step #{step.name}")
         count = clean_tree(nil)
         @utils.log("Cleaned #{count} items") if count.positive?
+        @utils.exec(["git", "reset", "--hard"])
       end
 
       ##

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toys-release
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Daniel Azuma
@@ -81,10 +81,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys-release/v0.3.0/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys-release/v0.3.1/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys/tree/main/toys-release
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys-release/v0.3.0
+  documentation_uri: https://dazuma.github.io/toys/gems/toys-release/v0.3.1
 rdoc_options: []
 require_paths:
 - lib