From 25a2cec80be65ac58c50ef1e3ceb78df8500a1c3 Mon Sep 17 00:00:00 2001 From: babblebey Date: Tue, 28 Jul 2026 15:18:20 +0100 Subject: [PATCH 1/2] feat: add validation for missing message option in plugin configuration --- src/content/docs/developer-guide/plugin.md | 29 ++++++++++++++++++---- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/src/content/docs/developer-guide/plugin.md b/src/content/docs/developer-guide/plugin.md index 5009422..26e058d 100644 --- a/src/content/docs/developer-guide/plugin.md +++ b/src/content/docs/developer-guide/plugin.md @@ -98,7 +98,30 @@ Let's say you want to verify that an option is passed. Plugin options are config That `message` value is passed to your plugin as part of `pluginConfig`. You can validate it in `verify.js` before using it later in the release process: -```js ins={2, 10, 12-21} +```js +import SemanticReleaseError from "@semantic-release/error"; + +/** + * Verify that the plugin has the configuration it needs. + */ +export default async (pluginConfig, context) => { + const { message } = pluginConfig; + + if (!message) { + throw new SemanticReleaseError( + "Missing `message` option.", + "EMISSINGMESSAGE", + "Add a `message` option to this plugin's entry in the `plugins` array.", + ); + } +}; +``` + +## Handling Errors + +To be detected and handled properly, errors thrown by the plugin must be instances of [SemanticReleaseError](https://github.com/semantic-release/error) (or subclasses). The example above shows the simplest case, throwing a single `SemanticReleaseError` when `message` is missing. If you need to report multiple validation problems at once, collect `SemanticReleaseError` instances and throw them together in an `AggregateError`, as shown in the example below. Other error types are treated as unexpected failures, bubble up to the final catch, and do not trigger `fail` plugins. + +```js ins={1, 14-20, 24-26} import AggregateError from "aggregate-error"; import SemanticReleaseError from "@semantic-release/error"; @@ -293,10 +316,6 @@ The above usage yields the following where `PLUGIN_PACKAGE_NAME` is automaticall Release step order is defined in [Release Steps](/foundation/release-steps/#step-sequence). For lifecycle hooks implemented by multiple plugins, semantic-release executes those lifecycle methods in the order the plugins are declared in the `plugins` configuration. -## Handling errors - -To be detected and handled properly, errors thrown by the plugin must be instances of [SemanticReleaseError](https://github.com/semantic-release/error) (or subclasses), as shown in the earlier `verify.js` validation example. If you need to report multiple validation problems at once, wrap those `SemanticReleaseError` instances in `AggregateError`. Other error types are treated as unexpected failures, bubble up to the final catch, and do not trigger `fail` plugins. - ## Advanced Knowledge that might be useful for plugin developers. From 47ccd896ce692adb293e2878aaae756d82662a85 Mon Sep 17 00:00:00 2001 From: babblebey Date: Tue, 28 Jul 2026 15:20:35 +0100 Subject: [PATCH 2/2] fix: correct heading casing for execution order in plugin documentation --- src/content/docs/developer-guide/plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/developer-guide/plugin.md b/src/content/docs/developer-guide/plugin.md index 26e058d..9f21ae8 100644 --- a/src/content/docs/developer-guide/plugin.md +++ b/src/content/docs/developer-guide/plugin.md @@ -312,7 +312,7 @@ The above usage yields the following where `PLUGIN_PACKAGE_NAME` is automaticall [3:24:04 PM] [semantic-release] [PLUGIN_PACKAGE_NAME] › ℹ Some message from plugin. ``` -## Execution order +## Execution Order Release step order is defined in [Release Steps](/foundation/release-steps/#step-sequence). For lifecycle hooks implemented by multiple plugins, semantic-release executes those lifecycle methods in the order the plugins are declared in the `plugins` configuration.