Add draftGithubReleases and improve documentation

.changeset/twelve-walls-eat.md

@@ -0,0 +1,5 @@
+---
+"@changesets/action": minor
+---
+
+Add draftGithubReleases

README.md

@@ -1,27 +1,43 @@
-# Changesets Release Action
+<h1>Changesets Release Action</h1>
 
 This action for [Changesets](https://github.com/atlassian/changesets) creates a pull request with all of the package versions updated and changelogs updated and when there are new changesets on [your configured `baseBranch`](https://github.com/changesets/changesets/blob/main/docs/config-file-options.md#basebranch-git-branch-name), the PR will be updated. When you're ready, you can merge the pull request and you can either publish the packages to npm manually or setup the action to do it for you.
 
+- [Usage](#usage)
+  - [Inputs](#inputs)
+  - [Outputs](#outputs)
+- [Example workflow:](#example-workflow)
+  - [Without Publishing](#without-publishing)
+  - [With Publishing](#with-publishing)
+    - [Workflow permissions](#workflow-permissions)
+  - [Custom Publishing](#custom-publishing)
+  - [With version script](#with-version-script)
+  - [With Yarn 2 / Plug'n'Play](#with-yarn-2--plugnplay)
+
 ## Usage
 
 ### Inputs
 
-- publish - The command to use to build and publish packages
-- version - The command to update version, edit CHANGELOG, read and delete changesets. Default to `changeset version` if not provided
-- commit - The commit message to use. Default to `Version Packages`
-- title - The pull request title. Default to `Version Packages`
-- setupGitUser - Sets up the git user for commits as `"github-actions[bot]"`. Default to `true`
-- createGithubReleases - A boolean value to indicate whether to create Github releases after `publish` or not. Default to `true`
-- cwd - Changes node's `process.cwd()` if the project is not located on the root. Default to `process.cwd()`
+| Name                   | Description                                                                        | Default             |
+| ---------------------- | ---------------------------------------------------------------------------------- | ------------------- |
+| `publish`              | The command used to build and publish packages.                                    |                     |
+| `version`              | The command to update the version, edit the CHANGELOG, and manage changesets.      | `changeset version` |
+| `commit`               | The commit message for version updates.                                            | `Version Packages`  |
+| `title`                | The title for the version update pull request.                                     | `Version Packages`  |
+| `setupGitUser`         | Configures the Git user for commits as `"github-actions[bot]"`.                    | `true`              |
+| `createGithubReleases` | Whether to create a GitHub release after publishing.                               | `true`              |
+| `draftGithubReleases`  | Whether to publish the GitHub release as a draft (unpublished).                    | `false`             |
+| `cwd`                  | The working directory for the process, useful when the project is not in the root. | `process.cwd()`     |
 
 ### Outputs
 
-- published - A boolean value to indicate whether a publishing has happened or not
-- publishedPackages - A JSON array to present the published packages. The format is `[{"name": "@xx/xx", "version": "1.2.0"}, {"name": "@xx/xy", "version": "0.8.9"}]`
+| Name                | Description                                                     | Type      | Example                                                                            |
+| ------------------- | --------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------- |
+| `publish`           | Indicates whether publishing has occurred.                      | `boolean` | `true`                                                                             |
+| `publishedPackages` | A JSON array listing the published packages and their versions. | `string`  | `[{"name": "@xx/xx", "version": "1.2.0"}, {"name": "@xx/xy", "version": "0.8.9"}]` |
 
-### Example workflow:
+## Example workflow:
 
-#### Without Publishing
+### Without Publishing
 
 Create a file at `.github/workflows/release.yml` with the following content.
 
@@ -57,7 +73,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-#### With Publishing
+### With Publishing
 
 Before you can setup this action with publishing, you'll need to have an [npm token](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) that can publish the packages in the repo you're setting up the action for and doesn't have 2FA on publish enabled ([2FA on auth can be enabled](https://docs.npmjs.com/about-two-factor-authentication)). You'll also need to [add it as a secret on your GitHub repo](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables) with the name `NPM_TOKEN`. Once you've done that, you can create a file at `.github/workflows/release.yml` with the following content.
 
@@ -122,7 +138,15 @@ For example, you can add a step before running the Changesets GitHub Action:
     NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```
 
-#### Custom Publishing
+#### Workflow permissions
+
+Some organizations and users may not have enabled GitHub Actions to create pull requests. To ensure this feature works correctly, you might need to enable it in your repository settings:
+
+![Workflows Permission](docs/workflow-permissions.png)
+
+You can find this setting at: **`https://github.com/user/repo/settings/actions`**
+
+### Custom Publishing
 
 If you want to hook into when publishing should occur but have your own publishing functionality, you can utilize the `hasChangesets` output.
 
@@ -164,7 +188,7 @@ jobs:
         run: yarn publish
 ```
 
-#### With version script
+### With version script
 
 If you need to add additional logic to the version command, you can do so by using a version script.
 
@@ -205,7 +229,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-#### With Yarn 2 / Plug'n'Play
+### With Yarn 2 / Plug'n'Play
 
 If you are using [Yarn Plug'n'Play](https://yarnpkg.com/features/pnp), you should use a custom `version` command so that the action can resolve the `changeset` CLI:
 

action.yml

@@ -5,31 +5,34 @@ runs:
   main: "dist/index.js"
 inputs:
   publish:
-    description: "The command to use to build and publish packages"
+    description: "The command used to build and publish packages."
     required: false
   version:
-    description: "The command to update version, edit CHANGELOG, read and delete changesets. Default to `changeset version` if not provided"
+    description: "The command to update the version, edit the CHANGELOG, and manage changesets. Defaults to `changeset version` if not provided."
     required: false
   cwd:
-    description: Sets the cwd for the node process. Default to `process.cwd()`
+    description: "The working directory for the process, useful when the project is not in the root. Defaults to `process.cwd()`."
     required: false
   commit:
-    description: |
-      The commit message. Default to `Version Packages`
+    description: "The commit message for version updates. Defaults to `Version Packages`."
     required: false
   title:
-    description: The pull request title. Default to `Version Packages`
+    description: "The title for the version update pull request. Defaults to `Version Packages`."
     required: false
   setupGitUser:
-    description: Sets up the git user for commits as `"github-actions[bot]"`. Default to `true`
+    description: 'Configures the Git user for commits as `"github-actions[bot]"`. Defaults to `true`.'
     required: false
     default: true
   createGithubReleases:
-    description: "A boolean value to indicate whether to create Github releases after `publish` or not"
+    description: "Whether to create a GitHub release after publishing. Defaults to `true`."
     required: false
     default: true
+  draftGithubReleases:
+    description: "Whether to publish the GitHub release as a draft (unpublished). Defaults to `false`."
+    required: false
+    default: false
   branch:
-    description: Sets the branch in which the action will run. Default to `github.ref_name` if not provided
+    description: "The branch in which the action will run. Defaults to `github.ref_name` if not provided."
     required: false
 outputs:
   published:

package.json

@@ -57,5 +57,6 @@
     "**/@octokit/core": "4.2.0",
     "trim": "^0.0.3",
     "y18n": "^4.0.1"
-  }
+  },
+  "packageManager": "yarn@1.22.22"
 }

src/index.ts

@@ -48,7 +48,9 @@ const getOptionalInput = (name: string) => core.getInput(name) || undefined;
 
   switch (true) {
     case !hasChangesets && !hasPublishScript:
-      core.info("No changesets present or were removed by merging release PR. Not publishing because no publish script found.");
+      core.info(
+        "No changesets present or were removed by merging release PR. Not publishing because no publish script found."
+      );
       return;
     case !hasChangesets && hasPublishScript: {
       core.info(
@@ -88,6 +90,7 @@ const getOptionalInput = (name: string) => core.getInput(name) || undefined;
         script: publishScript,
         githubToken,
         createGithubReleases: core.getBooleanInput("createGithubReleases"),
+        draftGithubReleases: core.getBooleanInput("draftGithubReleases"),
       });
 
       if (result.published) {

src/run.ts

@@ -60,7 +60,8 @@ const setupOctokit = (githubToken: string) => {
 
 const createRelease = async (
   octokit: ReturnType<typeof setupOctokit>,
-  { pkg, tagName }: { pkg: Package; tagName: string }
+  { pkg, tagName }: { pkg: Package; tagName: string },
+  draftGithubReleases: boolean
 ) => {
   try {
     let changelogFileName = path.join(pkg.dir, "CHANGELOG.md");
@@ -80,6 +81,7 @@ const createRelease = async (
       name: tagName,
       tag_name: tagName,
       body: changelogEntry.content,
+      draft: draftGithubReleases,
       prerelease: pkg.packageJson.version.includes("-"),
       ...github.context.repo,
     });
@@ -100,6 +102,7 @@ type PublishOptions = {
   script: string;
   githubToken: string;
   createGithubReleases: boolean;
+  draftGithubReleases: boolean;
   cwd?: string;
 };
 
@@ -118,6 +121,7 @@ export async function runPublish({
   script,
   githubToken,
   createGithubReleases,
+  draftGithubReleases,
   cwd = process.cwd(),
 }: PublishOptions): Promise<PublishResult> {
   const octokit = setupOctokit(githubToken);
@@ -158,10 +162,14 @@ export async function runPublish({
     if (createGithubReleases) {
       await Promise.all(
         releasedPackages.map((pkg) =>
-          createRelease(octokit, {
-            pkg,
-            tagName: `${pkg.packageJson.name}@${pkg.packageJson.version}`,
-          })
+          createRelease(
+            octokit,
+            {
+              pkg,
+              tagName: `${pkg.packageJson.name}@${pkg.packageJson.version}`,
+            },
+            draftGithubReleases
+          )
         )
       );
     }
@@ -181,10 +189,14 @@ export async function runPublish({
       if (match) {
         releasedPackages.push(pkg);
         if (createGithubReleases) {
-          await createRelease(octokit, {
-            pkg,
-            tagName: `v${pkg.packageJson.version}`,
-          });
+          await createRelease(
+            octokit,
+            {
+              pkg,
+              tagName: `v${pkg.packageJson.version}`,
+            },
+            draftGithubReleases
+          );
         }
         break;
       }