From e8c8f31fe7128381cfbad8cce440b0ba267cde12 Mon Sep 17 00:00:00 2001
From: Igor Danchenko <64441155+igordanchenko@users.noreply.github.com>
Date: Fri, 3 Jul 2026 23:18:49 -0700
Subject: [PATCH] docs: recommend pinning plugins and presets in npx command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The major-version pinning recommendation previously covered only
semantic-release itself, while the npx example listed plugins and presets
unpinned. An unpinned preset major can silently break releases — e.g.
`conventional-changelog-conventionalcommits@10` resolved against the
`conventional-changelog-writer@8` bundled by current semantic-release
produces empty release notes.

The example deliberately pins `conventional-changelog-conventionalcommits@9`
until release-notes-generator ships with `conventional-changelog-writer@9`.

See conventional-changelog/conventional-changelog#1495
---
 src/content/docs/usage/running.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/usage/running.md b/src/content/docs/usage/running.md
index ccbd0e4..0d829dd 100644
--- a/src/content/docs/usage/running.md
+++ b/src/content/docs/usage/running.md
@@ -21,7 +21,12 @@ npx --package semantic-release --package @semantic-release/exec --package conven
 
 ### Notes
 
-1. When running **semantic-release** with `npx`, we recommend setting at least the major version. For example, by using `npx semantic-release@25`. This way you control which major version of **semantic-release** is used by your pipeline, and thus avoid breaking the release when there's a new major version of **semantic-release**.
+1. When running **semantic-release** with `npx`, we recommend setting at least the major version. For example, by using `npx semantic-release@25`. This way you control which major version of **semantic-release** is used by your pipeline, and thus avoid breaking the release when there's a new major version of **semantic-release**. The same recommendation applies to any additional plugins and presets included in your `npx` command. Since plugins and presets, many of them developed by third-party projects, release new major versions on their own schedule, an unpinned plugin or preset can break your release just as unexpectedly. We recommend pinning all packages in your `npx` command:
+
+   ```sh
+   npx --package semantic-release@25 --package conventional-changelog-conventionalcommits@9 semantic-release
+   ```
+
 2. Pinning **semantic-release** to an exact version makes your releases even more deterministic. But pinning also means you, or a bot, must upgrade **semantic-release** when a new version is released.
 3. You can use [Renovate's regex manager](https://docs.renovatebot.com/modules/manager/regex/) to get automatic updates for **semantic-release** in either of the above scenarios. Put this in your Renovate configuration file: