semantic-release 20.0.0-beta.3 → 20.0.0

package/README.md

@@ -56,10 +56,10 @@ Tools such as [commitizen](https://github.com/commitizen/cz-cli) or [commitlint]
 
 The table below shows which commit message gets you which release type when `semantic-release` runs (using the default configuration):
 
-| Commit message                                                                                                                                                                                   | Release type               |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
-| `fix(pencil): stop graphite breaking when too much pressure applied`                                                                                                                             | ~~Patch~~ Fix Release      |
-| `feat(pencil): add 'graphiteWidth' option`                                                                                                                                                       | ~~Minor~~ Feature Release  |
+| Commit message                                                                                                                                                                                   | Release type                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `fix(pencil): stop graphite breaking when too much pressure applied`                                                                                                                             | ~~Patch~~ Fix Release                                                                                           |
+| `feat(pencil): add 'graphiteWidth' option`                                                                                                                                                       | ~~Minor~~ Feature Release                                                                                       |
 | `perf(pencil): remove graphiteWidth option`<br><br>`BREAKING CHANGE: The graphiteWidth option has been removed.`<br>`The default graphite width of 10mm is always used for performance reasons.` | ~~Major~~ Breaking Release <br /> (Note that the `BREAKING CHANGE: ` token must be in the footer of the commit) |
 
 ### Automation with CI
@@ -145,7 +145,6 @@ Let people know that your package is published using **semantic-release** and wh
 
 ```md
 [![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
-
 ```
 
 ## Team

package/bin/semantic-release.js

@@ -2,17 +2,17 @@
 
 /* eslint-disable no-var */
 
-import semver from 'semver';
-import { execa } from 'execa';
-import findVersions from 'find-versions';
-import cli from '../cli.js';
-import {createRequire} from 'node:module';
+import semver from "semver";
+import { execa } from "execa";
+import findVersions from "find-versions";
+import cli from "../cli.js";
+import { createRequire } from "node:module";
 
 const require = createRequire(import.meta.url);
-const { engines } = require('../package.json');
+const { engines } = require("../package.json");
 const { satisfies, lt } = semver;
 
-const MIN_GIT_VERSION = '2.7.1';
+const MIN_GIT_VERSION = "2.7.1";
 
 if (!satisfies(process.version, engines.node)) {
   console.error(
@@ -23,8 +23,8 @@ See https://github.com/semantic-release/semantic-release/blob/master/docs/suppor
   process.exit(1);
 }
 
-execa('git', ['--version'])
-  .then(({stdout}) => {
+execa("git", ["--version"])
+  .then(({ stdout }) => {
     const gitVersion = findVersions(stdout)[0];
     if (lt(gitVersion, MIN_GIT_VERSION)) {
       console.error(`[semantic-release]: Git version ${MIN_GIT_VERSION} is required. Found ${gitVersion}.`);

package/cli.js

@@ -1,47 +1,47 @@
-import util from 'node:util';
-import yargs from 'yargs';
-import {hideBin} from 'yargs/helpers';
-import hideSensitive from './lib/hide-sensitive.js';
+import util from "node:util";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import hideSensitive from "./lib/hide-sensitive.js";
 
 const stringList = {
-  type: 'string',
+  type: "string",
   array: true,
   coerce: (values) =>
-    values.length === 1 && values[0].trim() === 'false'
+    values.length === 1 && values[0].trim() === "false"
       ? []
-      : values.reduce((values, value) => values.concat(value.split(',').map((value) => value.trim())), []),
+      : values.reduce((values, value) => values.concat(value.split(",").map((value) => value.trim())), []),
 };
 
 export default async () => {
   const cli = yargs(hideBin(process.argv))
-    .command('$0', 'Run automated package publishing', (yargs) => {
+    .command("$0", "Run automated package publishing", (yargs) => {
       yargs.demandCommand(0, 0).usage(`Run automated package publishing
 
 Usage:
   semantic-release [options] [plugins]`);
     })
-    .option('b', {alias: 'branches', describe: 'Git branches to release from', ...stringList, group: 'Options'})
-    .option('r', {alias: 'repository-url', describe: 'Git repository URL', type: 'string', group: 'Options'})
-    .option('t', {alias: 'tag-format', describe: 'Git tag format', type: 'string', group: 'Options'})
-    .option('p', {alias: 'plugins', describe: 'Plugins', ...stringList, group: 'Options'})
-    .option('e', {alias: 'extends', describe: 'Shareable configurations', ...stringList, group: 'Options'})
-    .option('ci', {describe: 'Toggle CI verifications', type: 'boolean', group: 'Options'})
-    .option('verify-conditions', {...stringList, group: 'Plugins'})
-    .option('analyze-commits', {type: 'string', group: 'Plugins'})
-    .option('verify-release', {...stringList, group: 'Plugins'})
-    .option('generate-notes', {...stringList, group: 'Plugins'})
-    .option('prepare', {...stringList, group: 'Plugins'})
-    .option('publish', {...stringList, group: 'Plugins'})
-    .option('success', {...stringList, group: 'Plugins'})
-    .option('fail', {...stringList, group: 'Plugins'})
-    .option('debug', {describe: 'Output debugging information', type: 'boolean', group: 'Options'})
-    .option('d', {alias: 'dry-run', describe: 'Skip publishing', type: 'boolean', group: 'Options'})
-    .option('h', {alias: 'help', group: 'Options'})
+    .option("b", { alias: "branches", describe: "Git branches to release from", ...stringList, group: "Options" })
+    .option("r", { alias: "repository-url", describe: "Git repository URL", type: "string", group: "Options" })
+    .option("t", { alias: "tag-format", describe: "Git tag format", type: "string", group: "Options" })
+    .option("p", { alias: "plugins", describe: "Plugins", ...stringList, group: "Options" })
+    .option("e", { alias: "extends", describe: "Shareable configurations", ...stringList, group: "Options" })
+    .option("ci", { describe: "Toggle CI verifications", type: "boolean", group: "Options" })
+    .option("verify-conditions", { ...stringList, group: "Plugins" })
+    .option("analyze-commits", { type: "string", group: "Plugins" })
+    .option("verify-release", { ...stringList, group: "Plugins" })
+    .option("generate-notes", { ...stringList, group: "Plugins" })
+    .option("prepare", { ...stringList, group: "Plugins" })
+    .option("publish", { ...stringList, group: "Plugins" })
+    .option("success", { ...stringList, group: "Plugins" })
+    .option("fail", { ...stringList, group: "Plugins" })
+    .option("debug", { describe: "Output debugging information", type: "boolean", group: "Options" })
+    .option("d", { alias: "dry-run", describe: "Skip publishing", type: "boolean", group: "Options" })
+    .option("h", { alias: "help", group: "Options" })
     .strict(false)
     .exitProcess(false);
 
   try {
-    const {help, version, ...options} = cli.parse(process.argv.slice(2));
+    const { help, version, ...options } = cli.parse(process.argv.slice(2));
 
     if (Boolean(help) || Boolean(version)) {
       return 0;
@@ -49,16 +49,16 @@ Usage:
 
     if (options.debug) {
       // Debug must be enabled before other requires in order to work
-      (await import('debug')).default.enable('semantic-release:*');
+      (await import("debug")).default.enable("semantic-release:*");
     }
 
-    await (await import('./index.js')).default(options);
+    await (await import("./index.js")).default(options);
     return 0;
   } catch (error) {
-    if (error.name !== 'YError') {
-      process.stderr.write(hideSensitive(process.env)(util.inspect(error, {colors: true})));
+    if (error.name !== "YError") {
+      process.stderr.write(hideSensitive(process.env)(util.inspect(error, { colors: true })));
     }
 
     return 1;
   }
-}
+};

package/docs/developer-guide/js-api.md

@@ -3,43 +3,48 @@
 ## Usage
 
 ```js
-const semanticRelease = require('semantic-release');
-const {WritableStreamBuffer} = require('stream-buffers');
+const semanticRelease = require("semantic-release");
+const { WritableStreamBuffer } = require("stream-buffers");
 
 const stdoutBuffer = WritableStreamBuffer();
 const stderrBuffer = WritableStreamBuffer();
 
 try {
-  const result = await semanticRelease({
-    // Core options
-    branches: [
-      '+([0-9])?(.{+([0-9]),x}).x',
-      'master',
-      'next',
-      'next-major',
-      {name: 'beta', prerelease: true},
-      {name: 'alpha', prerelease: true}
-    ],
-    repositoryUrl: 'https://github.com/me/my-package.git',
-    // Shareable config
-    extends: 'my-shareable-config',
-    // Plugin options
-    githubUrl: 'https://my-ghe.com',
-    githubApiPathPrefix: '/api-prefix'
-  }, {
-    // Run semantic-release from `/path/to/git/repo/root` without having to change local process `cwd` with `process.chdir()`
-    cwd: '/path/to/git/repo/root',
-    // Pass the variable `MY_ENV_VAR` to semantic-release without having to modify the local `process.env`
-    env: {...process.env, MY_ENV_VAR: 'MY_ENV_VAR_VALUE'},
-    // Store stdout and stderr to use later instead of writing to `process.stdout` and `process.stderr`
-    stdout: stdoutBuffer,
-    stderr: stderrBuffer
-  });
+  const result = await semanticRelease(
+    {
+      // Core options
+      branches: [
+        "+([0-9])?(.{+([0-9]),x}).x",
+        "master",
+        "next",
+        "next-major",
+        { name: "beta", prerelease: true },
+        { name: "alpha", prerelease: true },
+      ],
+      repositoryUrl: "https://github.com/me/my-package.git",
+      // Shareable config
+      extends: "my-shareable-config",
+      // Plugin options
+      githubUrl: "https://my-ghe.com",
+      githubApiPathPrefix: "/api-prefix",
+    },
+    {
+      // Run semantic-release from `/path/to/git/repo/root` without having to change local process `cwd` with `process.chdir()`
+      cwd: "/path/to/git/repo/root",
+      // Pass the variable `MY_ENV_VAR` to semantic-release without having to modify the local `process.env`
+      env: { ...process.env, MY_ENV_VAR: "MY_ENV_VAR_VALUE" },
+      // Store stdout and stderr to use later instead of writing to `process.stdout` and `process.stderr`
+      stdout: stdoutBuffer,
+      stderr: stderrBuffer,
+    }
+  );
 
   if (result) {
-    const {lastRelease, commits, nextRelease, releases} = result;
+    const { lastRelease, commits, nextRelease, releases } = result;
 
-    console.log(`Published ${nextRelease.type} release version ${nextRelease.version} containing ${commits.length} commits.`);
+    console.log(
+      `Published ${nextRelease.type} release version ${nextRelease.version} containing ${commits.length} commits.`
+    );
 
     if (lastRelease.version) {
       console.log(`The last release was "${lastRelease.version}".`);
@@ -49,14 +54,14 @@ try {
       console.log(`The release was published with plugin "${release.pluginName}".`);
     }
   } else {
-    console.log('No release published.');
+    console.log("No release published.");
   }
 
   // Get stdout and stderr content
-  const logs = stdoutBuffer.getContentsAsString('utf8');
-  const errors = stderrBuffer.getContentsAsString('utf8');
+  const logs = stdoutBuffer.getContentsAsString("utf8");
+  const errors = stderrBuffer.getContentsAsString("utf8");
 } catch (err) {
-  console.error('The automated release failed with %O', err)
+  console.error("The automated release failed with %O", err);
 }
 ```
 
@@ -131,7 +136,7 @@ Type: `Object`
 Information related to the last release found:
 
 | Name    | Type     | Description                                                                                                                         |
-|---------|----------|-------------------------------------------------------------------------------------------------------------------------------------|
+| ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
 | version | `String` | The version of the last release.                                                                                                    |
 | gitHead | `String` | The sha of the last commit being part of the last release.                                                                          |
 | gitTag  | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the last release.                                  |
@@ -140,6 +145,7 @@ Information related to the last release found:
 **Notes**: If no previous release is found, `lastRelease` will be an empty `Object`.
 
 Example:
+
 ```js
 {
   gitHead: 'da39a3ee5e6b4b0d3255bfef95601890afd80709',
@@ -157,7 +163,7 @@ The list of commit included in the new release.<br>
 Each commit object has the following properties:
 
 | Name            | Type     | Description                                     |
-|-----------------|----------|-------------------------------------------------|
+| --------------- | -------- | ----------------------------------------------- |
 | commit          | `Object` | The commit abbreviated and full hash.           |
 | commit.long     | `String` | The commit hash.                                |
 | commit.short    | `String` | The commit abbreviated hash.                    |
@@ -179,6 +185,7 @@ Each commit object has the following properties:
 | committerDate   | `String` | The committer date.                             |
 
 Example:
+
 ```js
 [
   {
@@ -216,7 +223,7 @@ Type: `Object`
 Information related to the newly published release:
 
 | Name    | Type     | Description                                                                                                                   |
-|---------|----------|-------------------------------------------------------------------------------------------------------------------------------|
+| ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | type    | `String` | The [semver](https://semver.org) type of the release (`patch`, `minor` or `major`).                                           |
 | version | `String` | The version of the new release.                                                                                               |
 | gitHead | `String` | The sha of the last commit being part of the new release.                                                                     |
@@ -225,6 +232,7 @@ Information related to the newly published release:
 | channel | `String` | The distribution channel on which the next release will be made available (`undefined` for the default distribution channel). |
 
 Example:
+
 ```js
 {
   type: 'minor',
@@ -244,7 +252,7 @@ The list of releases published or made available to a distribution channel.<br>
 Each release object has the following properties:
 
 | Name       | Type     | Description                                                                                                    |
-|------------|----------|----------------------------------------------------------------------------------------------------------------|
+| ---------- | -------- | -------------------------------------------------------------------------------------------------------------- |
 | name       | `String` | **Optional.** The release name, only if set by the corresponding `publish` plugin.                             |
 | url        | `String` | **Optional.** The release URL, only if set by the corresponding `publish` plugin.                              |
 | type       | `String` | The [semver](https://semver.org) type of the release (`patch`, `minor` or `major`).                            |
@@ -256,6 +264,7 @@ Each release object has the following properties:
 | channel    | `String` | The distribution channel on which the release is available (`undefined` for the default distribution channel). |
 
 Example:
+
 ```js
 [
   {

package/docs/developer-guide/plugin.md

@@ -34,7 +34,7 @@ We recommend you setup a linting system to ensure good javascript practices are
 In your `index.js` file, you can start by writing the following code
 
 ```javascript
-const verify = require('./src/verify');
+const verify = require("./src/verify");
 
 let verified;
 
@@ -54,7 +54,7 @@ module.exports = { verifyConditions };
 Then, in your `src` folder, create a file called `verify.js` and add the following
 
 ```javascript
-const AggregateError = require('aggregate-error');
+const AggregateError = require("aggregate-error");
 
 /**
  * A method to verify that the user has given us a slack webhook url to post to
@@ -80,10 +80,10 @@ Let's say we want to verify that an `option` is passed. An `option` is a configu
 
 ```js
 {
-    prepare: {
-        path: "@semantic-release/my-special-plugin"
-        message: "My cool release message"
-    }
+  prepare: {
+    path: "@semantic-release/my-special-plugin";
+    message: "My cool release message";
+  }
 }
 ```
 
@@ -93,7 +93,7 @@ This `message` option will be passed to the `pluginConfig` object mentioned earl
 const { message } = pluginConfig;
 
 if (message.length) {
-    //...
+  //...
 }
 ```
 
@@ -101,103 +101,104 @@ if (message.length) {
 
 ### Common context keys
 
-* `stdout`
-* `stderr`
-* `logger`
+- `stdout`
+- `stderr`
+- `logger`
 
 ### Context object keys by lifecycle
 
 #### verifyConditions
 
 Initially the context object contains the following keys (`verifyConditions` lifecycle):
-* `cwd`
-  * Current working directory
-* `env`
-  * Environment variables
-* `envCi`
-  * Information about CI environment
-  * Contains (at least) the following keys:
-    * `isCi`
-      * Boolean, true if the environment is a CI environment
-    * `commit`
-      * Commit hash
-    * `branch`
-      * Current branch
-* `options`
-  * Options passed to `semantic-release` via CLI, configuration files etc.
-* `branch`
-  * Information on the current branch
-  * Object keys:
-    * `channel`
-    * `tags`
-    * `type`
-    * `name`
-    * `range`
-    * `accept`
-    * `main`
-* `branches`
-  * Information on branches
-  * List of branch objects (see above)
+
+- `cwd`
+  - Current working directory
+- `env`
+  - Environment variables
+- `envCi`
+  - Information about CI environment
+  - Contains (at least) the following keys:
+    - `isCi`
+      - Boolean, true if the environment is a CI environment
+    - `commit`
+      - Commit hash
+    - `branch`
+      - Current branch
+- `options`
+  - Options passed to `semantic-release` via CLI, configuration files etc.
+- `branch`
+  - Information on the current branch
+  - Object keys:
+    - `channel`
+    - `tags`
+    - `type`
+    - `name`
+    - `range`
+    - `accept`
+    - `main`
+- `branches`
+  - Information on branches
+  - List of branch objects (see above)
 
 #### analyzeCommits
 
 Compared to the verifyConditions, `analyzeCommits` lifecycle context has keys
 
-* `commits` (List)
-  * List of commits taken into account when determining the new version.
-  * Keys:
-    * `commit` (Object)
-      * Keys:
-        * `long` (String, Commit hash)
-        * `short` (String, Commit hash)
-    * `tree` (Object)
-      * Keys:
-        * `long` (String, Commit hash)
-        * `short` (String, Commit hash)
-    * `author` (Object)
-      * Keys:
-        * `name` (String)
-        * `email` (String)
-        * `date` (String, ISO 8601 timestamp)
-    * `committer` (Object)
-      * Keys:
-        * `name` (String)
-        * `email` (String)
-        * `date` (String, ISO 8601 timestamp)
-    * `subject` (String, Commit message subject)
-    * `body` (String, Commit message body)
-    * `hash` (String, Commit hash)
-    * `committerDate` (String, ISO 8601 timestamp)
-    * `message` (String)
-    * `gitTags` (String, List of git tags)
-* `releases` (List)
-* `lastRelease` (Object)
-  * Keys
-    * `version` (String)
-    * `gitTag` (String)
-    * `channels` (List)
-    * `gitHead` (String, Commit hash)
-    * `name` (String)
+- `commits` (List)
+  - List of commits taken into account when determining the new version.
+  - Keys:
+    - `commit` (Object)
+      - Keys:
+        - `long` (String, Commit hash)
+        - `short` (String, Commit hash)
+    - `tree` (Object)
+      - Keys:
+        - `long` (String, Commit hash)
+        - `short` (String, Commit hash)
+    - `author` (Object)
+      - Keys:
+        - `name` (String)
+        - `email` (String)
+        - `date` (String, ISO 8601 timestamp)
+    - `committer` (Object)
+      - Keys:
+        - `name` (String)
+        - `email` (String)
+        - `date` (String, ISO 8601 timestamp)
+    - `subject` (String, Commit message subject)
+    - `body` (String, Commit message body)
+    - `hash` (String, Commit hash)
+    - `committerDate` (String, ISO 8601 timestamp)
+    - `message` (String)
+    - `gitTags` (String, List of git tags)
+- `releases` (List)
+- `lastRelease` (Object)
+  - Keys
+    - `version` (String)
+    - `gitTag` (String)
+    - `channels` (List)
+    - `gitHead` (String, Commit hash)
+    - `name` (String)
 
 #### verifyRelease
 
 Additional keys:
 
-* `nextRelease` (Object)
-  * `type` (String)
-  * `channel` (String)
-  * `gitHead` (String, Git hash)
-  * `version` (String, version without `v`)
-  * `gitTag` (String, version with `v`)
-  * `name` (String)
-    
+- `nextRelease` (Object)
+  - `type` (String)
+  - `channel` (String)
+  - `gitHead` (String, Git hash)
+  - `version` (String, version without `v`)
+  - `gitTag` (String, version with `v`)
+  - `name` (String)
+
 #### generateNotes
 
 No new content in the context.
 
 #### addChannel
 
-*This is run only if there are releases that have been merged from a higher branch but not added on the channel of the current branch.*
+_This is run only if there are releases that have been merged from a higher branch but not added on the channel of the current branch._
 
 Context content is similar to lifecycle `verifyRelease`.
 
@@ -215,8 +216,8 @@ Lifecycles `success` and `fail` are mutually exclusive, only one of them will be
 
 Additional keys:
 
-* `releases`
-  * Populated by `publish` lifecycle
+- `releases`
+  - Populated by `publish` lifecycle
 
 #### fail
 
@@ -224,7 +225,7 @@ Lifecycles `success` and `fail` are mutually exclusive, only one of them will be
 
 Additional keys:
 
-* `errors`
+- `errors`
 
 ### Supporting Environment Variables
 
@@ -237,13 +238,15 @@ if (env.GITHUB_TOKEN) {
   //...
 }
 ```
+
 ## Logger
+
 Use `context.logger` to provide debug logging in the plugin.
 
 ```js
 const { logger } = context;
 
-logger.log('Some message from plugin.'). 
+logger.log('Some message from plugin.').
 ```
 
 The above usage yields the following where `PLUGIN_PACKAGE_NAME` is automatically inferred.
@@ -269,12 +272,13 @@ Knowledge that might be useful for plugin developers.
 While it may be trivial that multiple analyzeCommits (or any lifecycle plugins) can be defined, it is not that self-evident that the plugins executed AFTER the first one (for example, the default one: `commit-analyzer`) can change the result. This way it is possible to create more advanced rules or situations, e.g. if none of the commits would result in new release, then a default can be defined.
 
 The commit must be a known release type, for example the commit-analyzer has the following default types:
-* major
-* premajor
-* minor
-* preminor
-* patch
-* prepatch
-* prerelease
+
+- major
+- premajor
+- minor
+- preminor
+- patch
+- prepatch
+- prerelease
 
 If the analyzeCommits-lifecycle plugin does not return anything, then the earlier result is used, but if it returns a supported string value, then that overrides the previous result.