New CreatePullRequest workflow (knope-dev#579)

Co-authored-by: Dylan Anthony <[email protected]>

.changeset/add_a_changelogsection_variable_for_substitution.md

@@ -0,0 +1,32 @@
+---
+default: minor
+---
+
+#### Add a `ChangelogEntry` variable for substitution
+
+Anywhere that the existing `Version` variable can be used (for example, in [the `Command` step]), you can now also use `ChangelogEntry` to get the section of the changelog that corresponds to the current version. For example, you could (almost) replicate Knope's GitHub Release creation _without_ Knope's GitHub integration with a workflow like this:
+
+```toml
+[[workflows]]
+name = "release"
+
+[[workflows.steps]]
+type = "PrepareRelease"
+
+[[workflows.steps]]
+type = "Command"
+command = "git commit -m \"chore: prepare release $version\" && git push"
+
+[workflows.steps.variables]
+"$version" = "Version"
+
+[[workflows.steps]]
+type = "Command"
+command = "gh release create --title '$version' --notes '$changelog'"
+
+[workflows.steps.variables]
+"$version" = "Version"
+"$changelog" = "ChangelogEntry"
+```
+
+[the `Command` step]: https://knope-dev.github.io/knope/config/step/Command.html

.changeset/new_createpullrequest_step.md

@@ -0,0 +1,11 @@
+---
+default: minor
+---
+
+#### New `CreatePullRequest` step
+
+The new [`CreatePullRequest` step] allows you to create or update a pull request on GitHub. It's designed to be a nice way to preview and accept new releases via a pull request workflow, but could certainly work for more contexts as well! To see an example of the new PR-based release workflow, check out [Knope's prepare-release workflow] and [Knope's release workflow].
+
+[`CreatePullRequest step]: https://knope-dev.github.io/knope/docs/config/step/CreatePullRequest
+[Knope's prepare-release workflow]: https://github.com/knope-dev/knope/blob/e7292fa746fe1d81b84e5848815c02a0d8fc6f95/.github/workflows/prepare_release.yml
+[knope's release workflow]: https://github.com/knope-dev/knope/blob/e7292fa746fe1d81b84e5848815c02a0d8fc6f95/.github/workflows/release.yml

.changeset/only_consider_prereleases_newer_than_the_last_stable.md

@@ -0,0 +1,7 @@
+---
+default: patch
+---
+
+#### Only consider prereleases newer than the last stable
+
+This fixes a regression in the previous version of Knope where _all_ prereleases would be considered, rather than just those tagged after the latest stable version.

.github/workflows/prepare_release.yml

@@ -0,0 +1,22 @@
+on:
+  push:
+    branches: [main]
+name: Create Release PR
+jobs:
+  prepare-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.PAT }}
+      - name: Configure Git
+        run: |
+          git config --global user.name GitHub Actions
+          git config user.email [email protected]
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: "release"
+      - run: cargo run -- prepare-release --verbose
+        env:
+          GITHUB_TOKEN: ${{ secrets.PAT }}

.github/workflows/release.yml

@@ -1,35 +1,13 @@
 name: Release
 
 on:
-  workflow_dispatch
+  pull_request:
+    types: [ closed ]
+    branches: [ main ]
 
 jobs:
-  prepare-release:
-    runs-on: ubuntu-latest
-    outputs:
-      sha: ${{ steps.commit.outputs.sha }}
-    steps:
-      - uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.PAT }}
-      - uses: Swatinem/rust-cache@v2
-        with:
-          shared-key: "release"
-      - name: Import GPG key
-        uses: crazy-max/ghaction-import-gpg@v6
-        with:
-          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
-          git_user_signingkey: true
-          git_commit_gpgsign: true
-          git_push_gpgsign: false
-      - run: cargo run -- prepare-release
-      - name: Store commit
-        id: commit
-        run: echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
-
   build-artifacts:
-    needs: prepare-release
+    if:  github.head_ref == 'release' && github.event.pull_request.merged == true
     strategy:
       fail-fast: false
       matrix:
@@ -90,7 +68,7 @@ jobs:
           if-no-files-found: error
 
   release:
-    needs: [build-artifacts, prepare-release]
+    needs: [build-artifacts]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
@@ -111,7 +89,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.PAT }}
 
   publish-crate:
-    needs: [release, prepare-release]
+    needs: [release]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4

docs/src/SUMMARY.md

@@ -7,6 +7,7 @@
   - [Workflows](config/workflow.md)
   - [Steps](config/step/step.md)
     - [CreateChangeFile](config/step/CreateChangeFile.md)
+    - [CreatePullRequest](config/step/CreatePullRequest.md)
     - [PrepareRelease](config/step/PrepareRelease.md)
     - [Release](config/step/Release.md)
     - [BumpVersion](config/step/BumpVersion.md)
@@ -17,6 +18,7 @@
     - [SelectIssueFromBranch](config/step/SelectIssueFromBranch.md)
     - [SwitchBranches](config/step/SwitchBranches.md)
     - [RebaseBranch](config/step/RebaseBranch.md)
+  - [Variables](config/variables.md)
   - [Packages](config/packages.md)
   - [Jira](config/jira.md)
   - [GitHub](config/github.md)

docs/src/config/step/Command.md

@@ -15,13 +15,7 @@ variables = {"version" = "Version"}
 
 ## Variables
 
-The `variables` attribute of this step is an object where the key is the string you wish to substitute and the value is one of the available variables listed below. **take care when selecting a key to replace** as _any_ matching string that is found will be replaced. The order of this replacement is not guaranteed, so it is also possible for multiple variables to conflict with one another.
-
-### Available Variables
-
-1. `Version` will attempt to parse the project version using the same method as the [BumpVersion] step and substitute that string. It will select the first version found in any of the supported file names / formats to use for substitution. If no version can be found and parsed, this step will fail.
-
-1. `IssueBranch` will provide the same branch name that the [SwitchBranches] step would produce. You must have already selected an issue in this workflow using [`SelectJiraIssue`], [`SelectGitHubIssue`], or [`SelectIssueFromBranch`] before using this variable.
+The `variables` attribute of this step is an object where the key is the string you wish to substitute and the value is one of the [available variables](../variables.md). **take care when selecting a key to replace** as _any_ matching string that is found will be replaced. Replacements occur in the order they are declared in the config, so earlier substitutions may be replaced by later ones.
 
 [bumpversion]: ./BumpVersion.md
 [switchbranches]: ./SwitchBranches.md

docs/src/config/step/CreatePullRequest.md

@@ -0,0 +1,53 @@
+# `CreatePullRequest`
+
+Create a pull request on GitHub from the current branch to a specified branch. If a pull request for those already exists, this step will overwrite the title and body of the existing pull request.
+
+## Parameters
+
+### `base`
+
+The branch to create the pull request against. This is **required**.
+
+### `title.template`
+
+A template string for the title of the pull request. This is **required**.
+
+### `title.variables`
+
+An optional map of variables to use in the title template.
+
+### `body.template`
+
+A template string for the body of the pull request. This is **required**.
+
+### `body.variables`
+
+An optional map of variables to use in the body template.
+
+## Example
+
+An example workflow which creates a pull request from the current branch to `main` using the current version of the package as the title and the changelog entry for the current version as the body:
+
+```toml
+[[workflows]]
+name = "create-release-pull-request"
+
+[[workflows.steps]]
+type = "CreatePullRequest"
+
+[workflows.steps.base]
+default = "main"
+
+[workflows.steps.title]
+template = "chore: Release $version"
+variables = { "$version" = "Version" }
+
+[workflows.steps.body]
+template = "Merging this PR will release the following:\n\n$changelog"
+variables = { "$changelog" = "ChangelogEntry" }
+```
+
+For a full example of how this might be used with GitHub Actions to help automate releases, check out [Knope's prepare-release workflow] and [Knope's release workflow].
+
+[Knope's prepare-release workflow]: https://github.com/knope-dev/knope/blob/e7292fa746fe1d81b84e5848815c02a0d8fc6f95/.github/workflows/prepare_release.yml
+[knope's release workflow]: https://github.com/knope-dev/knope/blob/e7292fa746fe1d81b84e5848815c02a0d8fc6f95/.github/workflows/release.yml

docs/src/config/variables.md

@@ -0,0 +1,32 @@
+# Variables
+
+Some steps, notably [`Command`] and [`CreatePullRequest`] allow you to use variables in their configuration. Typically, this allows for string substitution with some context that Knope has. Variables are always configured by providing both the string that should be replaced and the name of the variable that should replace it, so you can customize your own syntax. For example, if you wanted to insert the current package version into a command, you might provide a `{"version": "Version"}` variable config. This would replace any instance of the string `version` with `Version`. If you wanted a bash-like syntax, you might use `{"$version": "Version"}` instead—pick whatever works best for you.
+
+## `Version`
+
+`Version` will attempt to parse the current package version and substitute that string. For example, you might use this to get the new version after running a [`PrepareRelease`] step.
+
+```admonish warning
+This variable can only be used when a single `[package]` is configured, there is currently no equivalent for multi-package projects.
+```
+
+## `ChangelogEntry`
+
+`ChangelogEntry` is the content of the changelog (if any) for the version that is indicated by the [`Version`](#version) variable. This follows the same rules as the [`Release`] step for creating a [GitHub changelog](./step/Release.md#github-release-notes), with the exception that it cannot use GitHub's auto-generated release notes. If no changelog entry can be found, the step fails.
+
+```admonish warning
+This variable can only be used when a single `[package]` is configured, there is currently no equivalent for multi-package projects.
+```
+
+## `IssueBranch`
+
+`IssueBranch` will provide the same branch name that the [`SwitchBranches`] step would produce. You must have already selected an issue in this workflow using [`SelectJiraIssue`], [`SelectGitHubIssue`], or [`SelectIssueFromBranch`] before using this variable.
+
+[`Command`]: ./step/Command.md
+[`CreatePullRequest`]: ./step/CreatePullRequest.md
+[`PrepareRelease`]: ./step/PrepareRelease.md
+[`Release`]: ./step/Release.md
+[`SwitchBranches`]: ./step/SwitchBranches.md
+[`SelectJiraIssue`]: ./step/SelectJiraIssue.md
+[`SelectGitHubIssue`]: ./step/SelectGitHubIssue.md
+[`SelectIssueFromBranch`]: ./step/SelectIssueFromBranch.md

knope.toml

@@ -17,16 +17,32 @@ path = "artifact/knope-aarch64-apple-darwin.tgz"
 [[workflows]]
 name = "prepare-release"
 
+[[workflows.steps]]
+type = "Command"
+command = "git switch -c release"
+
 [[workflows.steps]]
 type = "PrepareRelease"
 
 [[workflows.steps]]
 type = "Command"
-command = "git commit -m \"chore: prepare release $version\" && git push"
+command = "git commit -m \"chore: prepare release $version\" && git push --force --set-upstream origin release"
 
 [workflows.steps.variables]
 "$version" = "Version"
 
+[[workflows.steps]]
+type = "CreatePullRequest"
+base = "main"
+
+[workflows.steps.title]
+template = "chore: prepare release $version"
+variables = { "$version" = "Version" }
+
+[workflows.steps.body]
+template = "This PR was created by Knope. Merging it will create a new release\n\n$changelog"
+variables = { "$changelog" = "ChangelogEntry" }
+
 [[workflows]]
 name = "release"