feat: support for prereleases

.github/workflows/reusable-release-on-merge.yml

@@ -5,32 +5,45 @@ on:
     inputs:
       config_name:
         type: string
-        description: 'The name of the release drafter config file to use. Default: release-drafter.yml'
+        description: "The name of the release drafter config file to use. Default:
+          release-drafter.yml"
         required: false
-        default: 'release-drafter.yml'
+        default: "release-drafter.yml"
       commitish:
         type: string
-        description: 'The release target, i.e. branch or commit it should point to. Default: main'
+        description: "The release target, i.e. branch or commit it should point to.
+          Default: main"
         required: false
-        default: 'main'
+        default: "main"
       latest:
         type: boolean
-        description: 'Whether this should be marked as the latest release. Default: true'
+        description: "Whether this should be marked as the latest release. Default: true"
         required: false
         default: true
       disable_autolabeler:
         type: boolean
-        description: 'Whether to disable the autolabeler. Autolabeler should remain disabled if you label the pull requests with another workflow. Default: true'
+        description: "Whether to disable the autolabeler. Autolabeler should remain
+          disabled if you label the pull requests with another workflow.
+          Default: true"
         required: false
         default: true
-      run_post_release_workflow:
+      prerelease_identifier:
+        type: string
+        description: "The identifier to use for prereleases, e.g. \"beta\" or \"rc\". If
+          this is set, the release will be marked as a prerelease and the tag
+          name will be suffixed with this identifier. Default: empty string"
+        required: false
+        default: ""
+      publish:
         type: boolean
-        description: 'Trigger a post-release workflow at .github/workflows/release-post-actions.yml within your repository that receives a "version" input with the version that was just released. This workflow can do whatever you need, but generally is used to e.g. release a package to a package regsitry. Default: false'
+        description: "Whether to publish the release immediately. If false, the release
+          will be created as a draft. Default: true"
         required: false
-        default: false
+        default: true
     outputs:
       release_version:
-        description: 'The version of the release that was created by this workflow. This is the tag name of the release.'
+        description: "The version of the release that was created by this workflow. This
+          is the tag name of the release."
         value: ${{ jobs.create-release.outputs.release_version }}
 
 jobs:
@@ -48,7 +61,8 @@ jobs:
           config-name: ${{ inputs.config_name }}
           commitish: ${{ inputs.commitish }}
           disable-autolabeler: ${{ inputs.disable_autolabeler }}
-          publish: true
+          publish: ${{ inputs.publish }}
+          prerelease-identifier: ${{ inputs.prerelease_identifier }}
           latest: ${{ inputs.latest }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/reusable-release-on-merge.md

@@ -51,3 +51,80 @@ jobs:
 ```
 
 Be sure you replace `ref` with an appropriate ref to this repository.
+
+## Prerelease Workflow
+
+This workflow supports a single prerelease approach, where:
+
+- Passing a `prerelease_identifier` to the invocation will trigger a prerelease creation with a corresponding suffix
+- Prereleases accumulate changes as they are merged
+
+The suggested approach is to create and release a prerelease on merge to main, while also drafting the actual release for the next version, so that as soon as you're ready to release, you only have to publish the draft.
+
+You might configure your repository with the following example workflow, replacing `ref` with an appropriate ref to this repository:
+
+```yaml
+name: Publish Prerelease
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release-candidate-on-merge:
+    name: "Create and Publish Prerelease on Merge"
+    permissions:
+      contents: write
+      pull-requests: write
+    uses: launchbynttdata/launch-workflows/.github/workflows/reusable-release-on-merge.yml@ref
+    with:
+      prerelease_identifier: "rc"
+    secrets: inherit # pragma: allowlist secret
+
+  release-draft-on-merge:
+    name: "Draft Release on Merge"
+    permissions:
+      contents: write
+      pull-requests: write
+    uses: launchbynttdata/launch-workflows/.github/workflows/reusable-release-on-merge.yml@ref
+    with:
+      publish: false
+    secrets: inherit # pragma: allowlist secret
+
+```
+
+From a starting point of 1.0.0, a pull request labeled for a patch version update upon merge will:
+
+- Create a prerelease for version 1.0.1-rc0
+- Create a draft release for version 1.0.1
+
+If another pull request for a patch version update is merged before the draft is made public, another prerelease will be created and the following will exist:
+
+- 1.0.1-rc0 (prerelease)
+- 1.0.1-rc1 (prerelease, latest)
+- 1.0.1 (still drafted)
+
+Assuming the draft remains and a PR for a minor version is merged, the RC tag is moved forward and the draft is updated to the proper version:
+
+- 1.0.1-rc0 (our first PR)
+- 1.0.1-rc1 (no longer latest)
+- 1.1.0-rc0 (still a prerelease, latest)
+- 1.1.0 (our original draft is renamed and its body is updated)
+
+## Inputs
+
+| Input | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `config_name` | `string` | No | `release-drafter.yml` | The name of the release drafter config file to use. |
+| `commitish` | `string` | No | `main` | The release target, i.e. the branch or commit the release should point to. |
+| `latest` | `boolean` | No | `true` | Whether this release should be marked as the latest release. |
+| `disable_autolabeler` | `boolean` | No | `true` | Whether to disable the autolabeler. Should remain disabled if pull requests are labeled by another workflow. |
+| `prerelease_identifier` | `string` | No | `""` (empty) | The identifier to use for prereleases, e.g. `rc` or `beta`. When set, the release is marked as a prerelease and the tag is suffixed with this identifier. |
+| `publish` | `boolean` | No | `true` | Whether to publish the release immediately. When `false`, the release is created as a draft. |
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `release_version` | The tag name of the release created by this workflow. |