versionary 0.28.2 → 0.30.0

package/README.md

@@ -190,6 +190,12 @@ For a quick trial, use:
     combining `follows` with `monorepo-mode: "fixed"` are config errors.
     `follows` is non-transitive: A follows B does not imply A follows what B
     follows.
+  - per-package `exclude-paths` drops commits that only touch the listed paths
+    (relative to the package) from that package's bump and changelog. A
+    top-level `exclude-paths` applies to every package; the effective excludes
+    for a package are the union of the top-level list and the package's own
+    list. The top-level list also applies to a single-package (non-`packages`)
+    repository.
 
 ```jsonc
 // Editor extension that bundles the root CLI artifact

package/dist/cli/index.js

@@ -3,7 +3,7 @@ import { execFileSync } from "node:child_process";
 import { loadConfig } from "../config/load-config.js";
 import { prependChangelog, renderReleasePlanChangelog, } from "../release/changelog.js";
 import { createReleasePlan } from "../release/plan.js";
-import { closeStaleReviewRequestIfExists, consumeNextReleaseFile, isReleaseCommitMessage, openOrUpdateReviewRequest, prepareReleasePr, pushReleaseBranch, readNextReleaseHighlights, } from "../release/pr.js";
+import { closeStaleReviewRequestIfExists, consumeNextReleaseFile, isReleaseCommitMessage, openOrUpdateReviewRequest, prepareReleasePr, pushReleaseBranch, resolveReleaseHighlights, } from "../release/pr.js";
 import { runRelease, runReleaseDetailed } from "../release/release.js";
 import { verifyProject } from "../release/verify-project.js";
 function printVerifyResult() {
@@ -196,16 +196,17 @@ async function main() {
             return 0;
         }
         const loaded = loadConfig();
-        const highlightsRead = readNextReleaseHighlights(process.cwd(), loaded.config);
-        const highlights = highlightsRead?.content ?? "";
-        const section = renderReleasePlanChangelog(plan, { highlights });
+        const highlightsResult = resolveReleaseHighlights(process.cwd(), loaded.config, plan.changelogFile, plan.changelogFormat, logger);
+        const section = renderReleasePlanChangelog(plan, {
+            highlights: highlightsResult.highlights,
+        });
         if (!write) {
             console.log(section);
             return 0;
         }
         prependChangelog(process.cwd(), plan.changelogFile, section, plan.changelogFormat);
-        if (highlightsRead) {
-            consumeNextReleaseFile(process.cwd(), highlightsRead.filePath);
+        if (highlightsResult.source === "file" && highlightsResult.filePath) {
+            consumeNextReleaseFile(process.cwd(), highlightsResult.filePath);
         }
         console.log(`Updated ${plan.changelogFile}`);
         return 0;

package/dist/config/schema.d.ts

@@ -30,6 +30,7 @@ export declare const configSchema: z.ZodObject<{
     "bump-minor-pre-major": z.ZodOptional<z.ZodBoolean>;
     "allow-stable-major": z.ZodOptional<z.ZodBoolean>;
     "include-commit-authors": z.ZodOptional<z.ZodBoolean>;
+    "exclude-paths": z.ZodOptional<z.ZodArray<z.ZodString>>;
     "release-type": z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     packages: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         "release-type": z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;

package/dist/config/schema.js

@@ -82,6 +82,7 @@ export const configSchema = z
     "bump-minor-pre-major": z.boolean().optional(),
     "allow-stable-major": z.boolean().optional(),
     "include-commit-authors": z.boolean().optional(),
+    "exclude-paths": z.array(z.string()).optional(),
     "release-type": z
         .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
         .optional(),

package/dist/release/changelog.d.ts

@@ -25,6 +25,26 @@ export declare function renderReleasePlanChangelog(plan: ReleasePlan, options?:
 }): string;
 /** @deprecated Use renderReleasePlanChangelog. */
 export declare function renderSimpleChangelog(plan: SimplePlan): string;
+/**
+ * Locate a manual-notes block at the top of an existing changelog and split it
+ * out. The notes block is the first release-level heading whose text is not a
+ * version (`##` for markdown, `#` for r-news), captured up to — but excluding —
+ * the first subsequent version heading at the same level.
+ *
+ * Returns the captured prose as `highlights` (the heading line itself dropped,
+ * trimmed) and the changelog with that block removed as `body`. When the first
+ * release-level heading is already a version, or there is none, nothing is
+ * stripped and `highlights` is empty.
+ *
+ * Only the topmost heading is ever eligible, and capture stops at the first
+ * version heading, so prior releases are never swallowed. For r-news this also
+ * subsumes the conventional `# pkg (development version)` header, whose body
+ * (if any) becomes the release notes.
+ */
+export declare function extractUnreleasedNotes(existing: string, format?: VersionaryChangelogFormat): {
+    highlights: string;
+    body: string;
+};
 export declare function prependChangelog(cwd: string, changelogFile: string, section: string, format?: VersionaryChangelogFormat): void;
 export declare function renderRNewsReleaseNotes(input: {
     packageName: string;

package/dist/release/changelog.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { applyRevertSuppression, inferReleaseTypeFromParsedCommit, parseConventionalCommitMessage, } from "../git/commits.js";
 import { resolveRepositoryWebBaseUrl } from "../git/repo-url.js";
 import { resolvePackageDependencies, } from "./plan.js";
+import { isVersionHeading } from "./semver.js";
 const REVIEW_REQUEST_FOOTER = "---\n\nThis PR was generated by [Versionary](https://github.com/jolars/versionary).";
 function formatDate() {
     return new Date().toISOString().slice(0, 10);
@@ -201,15 +202,63 @@ export function renderReleasePlanChangelog(plan, options = {}) {
 export function renderSimpleChangelog(plan) {
     return renderReleasePlanChangelog(plan);
 }
+/**
+ * Locate a manual-notes block at the top of an existing changelog and split it
+ * out. The notes block is the first release-level heading whose text is not a
+ * version (`##` for markdown, `#` for r-news), captured up to — but excluding —
+ * the first subsequent version heading at the same level.
+ *
+ * Returns the captured prose as `highlights` (the heading line itself dropped,
+ * trimmed) and the changelog with that block removed as `body`. When the first
+ * release-level heading is already a version, or there is none, nothing is
+ * stripped and `highlights` is empty.
+ *
+ * Only the topmost heading is ever eligible, and capture stops at the first
+ * version heading, so prior releases are never swallowed. For r-news this also
+ * subsumes the conventional `# pkg (development version)` header, whose body
+ * (if any) becomes the release notes.
+ */
+export function extractUnreleasedNotes(existing, format = "markdown-changelog") {
+    const headingPattern = format === "r-news" ? /^#(?!#)\s+/u : /^##(?!#)\s+/u;
+    const lines = existing.split("\n");
+    let firstHeadingIdx = -1;
+    for (let index = 0; index < lines.length; index += 1) {
+        if (headingPattern.test(lines[index])) {
+            firstHeadingIdx = index;
+            break;
+        }
+    }
+    if (firstHeadingIdx === -1 || isVersionHeading(lines[firstHeadingIdx])) {
+        return { highlights: "", body: existing };
+    }
+    let nextVersionIdx = lines.length;
+    for (let index = firstHeadingIdx + 1; index < lines.length; index += 1) {
+        if (headingPattern.test(lines[index]) && isVersionHeading(lines[index])) {
+            nextVersionIdx = index;
+            break;
+        }
+    }
+    const highlights = lines
+        .slice(firstHeadingIdx + 1, nextVersionIdx)
+        .join("\n")
+        .trim();
+    const body = [
+        ...lines.slice(0, firstHeadingIdx),
+        ...lines.slice(nextVersionIdx),
+    ].join("\n");
+    return { highlights, body };
+}
 export function prependChangelog(cwd, changelogFile, section, format = "markdown-changelog") {
     const changelogPath = path.join(cwd, changelogFile);
-    const existing = fs.existsSync(changelogPath)
+    const existingRaw = fs.existsSync(changelogPath)
         ? fs.readFileSync(changelogPath, "utf8")
         : "";
+    // Strip any manual-notes block; its prose is folded into `section` upstream,
+    // so leaving it here would duplicate it.
+    const { body: existing } = extractUnreleasedNotes(existingRaw, format);
     if (format === "r-news") {
-        const bodyWithoutDevHeader = existing.replace(/^#\s+.+\s+\(development version\)\s*(?:\r?\n)*/u, "");
-        const separator = bodyWithoutDevHeader.length > 0 ? "\n\n" : "";
-        const next = `${`${section}${separator}${bodyWithoutDevHeader}`.trimEnd()}\n`;
+        const separator = existing.length > 0 ? "\n\n" : "";
+        const next = `${`${section}${separator}${existing}`.trimEnd()}\n`;
         fs.writeFileSync(changelogPath, next, "utf8");
         return;
     }

package/dist/release/plan.js

@@ -58,9 +58,22 @@ export function createReleasePlan(cwd = process.cwd()) {
             throw new Error(`Versionary requires ${packageContext.versionFile} to exist for package "${pkg.path}".`);
         }
         const packageCurrentVersion = packageContext.strategy.readVersion(cwd, packageContext.config);
-        const parsedCommits = !hasPackages && pkg.path === "."
-            ? getParsedCommitsSinceLastTag(cwd, baselineSha)
-            : getParsedCommitsForPath(cwd, releaseTargetByPath.get(pkg.path)?.tag ?? baselineSha, pkg.path, pkg.config["exclude-paths"] ?? []);
+        const excludePaths = [
+            ...new Set([
+                ...(loaded.config["exclude-paths"] ?? []),
+                ...(pkg.config["exclude-paths"] ?? []),
+            ]),
+        ];
+        const isImplicitRoot = !hasPackages && pkg.path === ".";
+        let parsedCommits;
+        if (isImplicitRoot && excludePaths.length === 0) {
+            parsedCommits = getParsedCommitsSinceLastTag(cwd, baselineSha);
+        }
+        else {
+            parsedCommits = getParsedCommitsForPath(cwd, isImplicitRoot
+                ? baselineSha
+                : (releaseTargetByPath.get(pkg.path)?.tag ?? baselineSha), pkg.path, excludePaths);
+        }
         const effectiveCommits = applyRevertSuppression(parsedCommits);
         const commits = effectiveCommits;
         const releaseType = analyzeParsedCommits(parsedCommits);

package/dist/release/pr.d.ts

@@ -1,5 +1,5 @@
 import type { ParsedCommit } from "../git/commits.js";
-import type { VersionaryConfig } from "../types/config.js";
+import type { VersionaryChangelogFormat, VersionaryConfig } from "../types/config.js";
 import type { VersionaryPluginContext } from "../types/plugins.js";
 import { type ReleasePlan, type SimplePlan } from "./plan.js";
 export declare function getNextReleaseFile(config: VersionaryConfig): string;
@@ -10,6 +10,22 @@ export declare function readNextReleaseHighlights(cwd: string, config: Versionar
 export declare function consumeNextReleaseFile(cwd: string, filePath: string): {
     tracked: boolean;
 };
+/**
+ * Read the manual-notes ("Unreleased") prose from the top of a changelog file.
+ * Returns an empty string when the file is absent or has no notes block.
+ */
+export declare function readChangelogHighlights(cwd: string, changelogFile: string, format: VersionaryChangelogFormat): string;
+export interface ResolvedReleaseHighlights {
+    highlights: string;
+    source: "changelog" | "file" | "none";
+    filePath?: string;
+}
+/**
+ * Resolve release highlights, preferring an editable "Unreleased" section at the
+ * top of the changelog. Falls back to the deprecated `NEXT_RELEASE.md` file
+ * (emitting a warning) so existing setups keep working.
+ */
+export declare function resolveReleaseHighlights(cwd: string, config: VersionaryConfig, changelogFile: string, format: VersionaryChangelogFormat, logger?: VersionaryPluginContext["logger"]): ResolvedReleaseHighlights;
 export declare function splitSafeDirtyFiles(files: string[]): {
     ignored: string[];
     blocking: string[];

package/dist/release/pr.js

@@ -6,7 +6,7 @@ import { ensureGitIdentity } from "../git/identity.js";
 import { getScmClient } from "../scm/client.js";
 import { resolvePackageStrategyContext, resolveReleaseName, } from "../strategy/package-context.js";
 import { applyConfiguredArtifactRules } from "./artifact-rules.js";
-import { prependChangelog, renderReleaseNotesSection, renderReleasePlanChangelog, renderReviewRequestFooter, } from "./changelog.js";
+import { extractUnreleasedNotes, prependChangelog, renderReleaseNotesSection, renderReleasePlanChangelog, renderReviewRequestFooter, } from "./changelog.js";
 import { createReleasePlan, getChangelogDefaults, resolvePackageDependencies, } from "./plan.js";
 import { getBaselineStatePath, writeBaselineSha, } from "./state.js";
 const SAFE_DIRTY_FILES = new Set([
@@ -49,6 +49,39 @@ export function consumeNextReleaseFile(cwd, filePath) {
     }
     return { tracked };
 }
+/**
+ * Read the manual-notes ("Unreleased") prose from the top of a changelog file.
+ * Returns an empty string when the file is absent or has no notes block.
+ */
+export function readChangelogHighlights(cwd, changelogFile, format) {
+    const changelogPath = path.join(cwd, changelogFile);
+    if (!fs.existsSync(changelogPath)) {
+        return "";
+    }
+    const existing = fs.readFileSync(changelogPath, "utf8");
+    return extractUnreleasedNotes(existing, format).highlights;
+}
+/**
+ * Resolve release highlights, preferring an editable "Unreleased" section at the
+ * top of the changelog. Falls back to the deprecated `NEXT_RELEASE.md` file
+ * (emitting a warning) so existing setups keep working.
+ */
+export function resolveReleaseHighlights(cwd, config, changelogFile, format, logger) {
+    const fromChangelog = readChangelogHighlights(cwd, changelogFile, format);
+    if (fromChangelog.length > 0) {
+        return { highlights: fromChangelog, source: "changelog" };
+    }
+    const fromFile = readNextReleaseHighlights(cwd, config);
+    if (fromFile) {
+        logger?.warn(`${fromFile.filePath} is deprecated; add release notes under an "Unreleased" heading at the top of ${changelogFile} instead.`);
+        return {
+            highlights: fromFile.content,
+            source: "file",
+            filePath: fromFile.filePath,
+        };
+    }
+    return { highlights: "", source: "none" };
+}
 function listTrackedDirtyFiles(cwd) {
     const status = execFileSync("git", ["status", "--porcelain", "--untracked-files=no"], {
         cwd,
@@ -264,16 +297,18 @@ export function prepareReleasePr(cwd = process.cwd(), options = {}) {
     }
     const updatedArtifactFiles = applyConfiguredArtifactRules(cwd, loaded.config, plan);
     const packageReleaseMetadata = buildPackageReleaseMetadata(cwd, plan, loaded.config);
-    const nextReleaseRead = readNextReleaseHighlights(cwd, loaded.config);
-    const highlights = nextReleaseRead?.content ?? "";
+    const highlightsResult = resolveReleaseHighlights(cwd, loaded.config, plan.changelogFile, plan.changelogFormat, options.logger);
+    const highlights = highlightsResult.highlights;
     const section = renderReleasePlanChangelog(plan, { highlights, cwd });
     prependChangelog(cwd, plan.changelogFile, section, plan.changelogFormat);
     const updatedChangelogFiles = [plan.changelogFile];
     let consumedHighlightsPath = null;
-    if (nextReleaseRead) {
-        const { tracked } = consumeNextReleaseFile(cwd, nextReleaseRead.filePath);
+    // The changelog "Unreleased" block is stripped in-place by prependChangelog;
+    // only the legacy side file needs explicit consumption and staging.
+    if (highlightsResult.source === "file" && highlightsResult.filePath) {
+        const { tracked } = consumeNextReleaseFile(cwd, highlightsResult.filePath);
         if (tracked) {
-            consumedHighlightsPath = nextReleaseRead.filePath;
+            consumedHighlightsPath = highlightsResult.filePath;
         }
     }
     for (const packagePlan of plan.packages ?? []) {
@@ -292,6 +327,8 @@ export function prepareReleasePr(cwd = process.cwd(), options = {}) {
         if (!packageMetadata) {
             continue;
         }
+        const packageChangelogPath = path.posix.join(packagePlan.path, packageChangelogFile);
+        const packageHighlights = readChangelogHighlights(cwd, packageChangelogPath, "markdown-changelog");
         const packageSection = renderReleaseNotesSection({
             currentVersion: packagePlan.currentVersion,
             nextVersion: packagePlan.nextVersion,
@@ -299,9 +336,10 @@ export function prepareReleasePr(cwd = process.cwd(), options = {}) {
             tagPrefix: packageMetadata.tagPrefix,
             cwd,
             dependencies: resolvePackageDependencies(plan, packagePlan.path),
+            highlights: packageHighlights,
         });
-        prependChangelog(cwd, path.posix.join(packagePlan.path, packageChangelogFile), packageSection, "markdown-changelog");
-        updatedChangelogFiles.push(path.posix.join(packagePlan.path, packageChangelogFile));
+        prependChangelog(cwd, packageChangelogPath, packageSection, "markdown-changelog");
+        updatedChangelogFiles.push(packageChangelogPath);
     }
     const releaseTargets = buildReleaseTargets(cwd, plan, loaded.config);
     const branch = plan.releaseBranchPrefix;

package/dist/release/release.js

@@ -8,7 +8,7 @@ import { resolveVersionStrategy } from "../strategy/resolve.js";
 import { getChangelogDefaults } from "./plan.js";
 import { isReleaseCommitMessage } from "./pr.js";
 import { executeIdempotentReleaseTarget } from "./recovery.js";
-import { readReleaseTargets } from "./state.js";
+import { readPendingReleaseTargets } from "./state.js";
 function escapeRegExp(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
@@ -147,7 +147,7 @@ export async function runReleaseDetailed(cwd = process.cwd(), options = {}) {
     const referenceCommentMode = loaded.config["release-reference-comments"] ?? "off";
     const version = strategy.readVersion(cwd, loaded.config);
     const defaultTag = `v${version}`;
-    const releaseTargets = readReleaseTargets(cwd);
+    const releaseTargets = readPendingReleaseTargets(cwd);
     const targets = releaseTargets.length > 0
         ? releaseTargets
         : [
@@ -195,7 +195,8 @@ export async function runReleaseDetailed(cwd = process.cwd(), options = {}) {
             tagStatus: outcome.tagStatus,
             metadataStatus: outcome.metadataStatus,
         });
-        if (references.length > 0) {
+        const releaseWasCreated = outcome.tagStatus === "created" || outcome.metadataStatus === "created";
+        if (references.length > 0 && releaseWasCreated) {
             referenceReleases.push({
                 name: resolveTargetPackageName(cwd, loaded.config, target.path),
                 tag: outcome.tag,

package/dist/release/semver.d.ts

@@ -12,5 +12,17 @@ export interface BumpVersionOptions {
 }
 export declare function parseVersion(version: string): ParsedVersion;
 export declare function isValidVersion(version: string): boolean;
+/**
+ * Decide whether a changelog heading denotes a released version (e.g.
+ * `## [0.28.2](url) (2026-06-02)`, `## 1.2.3`, `## v1.2.3`, `## 0.28.2.9000`)
+ * rather than a manual-notes heading (e.g. `## Unreleased`, `## Upcoming`).
+ *
+ * Intentionally liberal: a heading counts as a version if it contains any
+ * version-like token that {@link isValidVersion} accepts. This errs toward
+ * "it's a version", so a real release heading is never mistaken for a notes
+ * block (and therefore never stripped). Dates such as `2026-06-02` use dashes,
+ * not dots, so they never match the three-component token.
+ */
+export declare function isVersionHeading(heading: string): boolean;
 export declare function compareVersions(leftRaw: string, rightRaw: string): number;
 export declare function bumpVersion(current: string, releaseType: Exclude<ReleaseType, null>, options?: BumpVersionOptions): string;

package/dist/release/semver.js

@@ -38,6 +38,25 @@ export function parseVersion(version) {
 export function isValidVersion(version) {
     return SEMVER_PATTERN.test(normalizeVersionInput(version));
 }
+const VERSION_TOKEN_PATTERN = /v?(\d+\.\d+\.\d+(?:\.\d+)?)/u;
+/**
+ * Decide whether a changelog heading denotes a released version (e.g.
+ * `## [0.28.2](url) (2026-06-02)`, `## 1.2.3`, `## v1.2.3`, `## 0.28.2.9000`)
+ * rather than a manual-notes heading (e.g. `## Unreleased`, `## Upcoming`).
+ *
+ * Intentionally liberal: a heading counts as a version if it contains any
+ * version-like token that {@link isValidVersion} accepts. This errs toward
+ * "it's a version", so a real release heading is never mistaken for a notes
+ * block (and therefore never stripped). Dates such as `2026-06-02` use dashes,
+ * not dots, so they never match the three-component token.
+ */
+export function isVersionHeading(heading) {
+    const match = heading.match(VERSION_TOKEN_PATTERN);
+    if (!match?.[1]) {
+        return false;
+    }
+    return isValidVersion(match[1]);
+}
 function isNumericIdentifier(identifier) {
     return /^(0|[1-9]\d*)$/u.test(identifier);
 }

package/dist/release/state.d.ts

@@ -6,4 +6,5 @@ export interface ReleaseTargetState {
 export declare function getBaselineStatePath(cwd: string): string;
 export declare function readBaselineSha(cwd?: string): string | null;
 export declare function readReleaseTargets(cwd?: string): ReleaseTargetState[];
+export declare function readPendingReleaseTargets(cwd?: string): ReleaseTargetState[];
 export declare function writeBaselineSha(cwd?: string, sha?: string, releaseTargets?: ReleaseTargetState[]): void;

package/dist/release/state.js

@@ -5,6 +5,7 @@ import { loadConfig } from "../config/load-config.js";
 const MANIFEST_VERSION_KEY = "manifest-version";
 const BASELINE_SHA_KEY = "baseline-sha";
 const RELEASE_TARGETS_KEY = "release-targets";
+const PENDING_RELEASE_TARGETS_KEY = "pending-release-targets";
 function parseStateFile(raw, filePath) {
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
@@ -19,24 +20,28 @@ function parseStateFile(raw, filePath) {
         typeof manifest[BASELINE_SHA_KEY] !== "string") {
         throw new Error(`Invalid release manifest at ${filePath}: ${BASELINE_SHA_KEY} must be a string.`);
     }
-    if (manifest[RELEASE_TARGETS_KEY] !== undefined &&
-        !Array.isArray(manifest[RELEASE_TARGETS_KEY])) {
-        throw new Error(`Invalid release manifest at ${filePath}: ${RELEASE_TARGETS_KEY} must be an array.`);
+    validateReleaseTargets(manifest[RELEASE_TARGETS_KEY], RELEASE_TARGETS_KEY, filePath);
+    validateReleaseTargets(manifest[PENDING_RELEASE_TARGETS_KEY], PENDING_RELEASE_TARGETS_KEY, filePath);
+    return manifest;
+}
+function validateReleaseTargets(value, key, filePath) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`Invalid release manifest at ${filePath}: ${key} must be an array.`);
     }
-    if (Array.isArray(manifest[RELEASE_TARGETS_KEY])) {
-        for (const target of manifest[RELEASE_TARGETS_KEY]) {
-            if (!target || typeof target !== "object" || Array.isArray(target)) {
-                throw new Error(`Invalid release manifest at ${filePath}: each release target must be an object.`);
-            }
-            const record = target;
-            if (typeof record.path !== "string" ||
-                typeof record.version !== "string" ||
-                typeof record.tag !== "string") {
-                throw new Error(`Invalid release manifest at ${filePath}: ${RELEASE_TARGETS_KEY} must contain string path, version, and tag.`);
-            }
+    for (const target of value) {
+        if (!target || typeof target !== "object" || Array.isArray(target)) {
+            throw new Error(`Invalid release manifest at ${filePath}: each release target must be an object.`);
+        }
+        const record = target;
+        if (typeof record.path !== "string" ||
+            typeof record.version !== "string" ||
+            typeof record.tag !== "string") {
+            throw new Error(`Invalid release manifest at ${filePath}: ${key} must contain string path, version, and tag.`);
         }
     }
-    return manifest;
 }
 export function getBaselineStatePath(cwd) {
     const loaded = loadConfig(cwd);
@@ -62,6 +67,9 @@ export function readBaselineSha(cwd = process.cwd()) {
     const parsed = parseStateFile(fs.readFileSync(filePath, "utf8"), filePath);
     return parsed[BASELINE_SHA_KEY] ?? null;
 }
+// Accumulated per-package baseline: the latest released tag for every package
+// ever released. `plan` uses these tags as the commit-range floor per package,
+// so this list must persist entries across releases rather than be replaced.
 export function readReleaseTargets(cwd = process.cwd()) {
     const filePath = getBaselineStatePath(cwd);
     if (!fs.existsSync(filePath)) {
@@ -70,6 +78,18 @@ export function readReleaseTargets(cwd = process.cwd()) {
     const parsed = parseStateFile(fs.readFileSync(filePath, "utf8"), filePath);
     return parsed[RELEASE_TARGETS_KEY] ?? [];
 }
+// The publish set introduced by the current release PR. `release` consumes this
+// so it only publishes/announces what this PR bumped, not every package in the
+// accumulated baseline. Falls back to the accumulated targets for manifests
+// written before this key existed (legacy compatibility).
+export function readPendingReleaseTargets(cwd = process.cwd()) {
+    const filePath = getBaselineStatePath(cwd);
+    if (!fs.existsSync(filePath)) {
+        return [];
+    }
+    const parsed = parseStateFile(fs.readFileSync(filePath, "utf8"), filePath);
+    return (parsed[PENDING_RELEASE_TARGETS_KEY] ?? parsed[RELEASE_TARGETS_KEY] ?? []);
+}
 export function writeBaselineSha(cwd = process.cwd(), sha, releaseTargets) {
     const baselineShaValue = sha ??
         execFileSync("git", ["rev-parse", "HEAD"], {
@@ -82,6 +102,9 @@ export function writeBaselineSha(cwd = process.cwd(), sha, releaseTargets) {
         ? parseStateFile(fs.readFileSync(filePath, "utf8"), filePath)
         : {};
     const existingTargets = existing[RELEASE_TARGETS_KEY] ?? [];
+    // Merge the current targets into the accumulated baseline (latest tag per
+    // path wins, since `releaseTargets` is appended last), but record the current
+    // targets verbatim as the pending publish set.
     const nextTargets = releaseTargets === undefined
         ? existingTargets
         : [
@@ -90,10 +113,14 @@ export function writeBaselineSha(cwd = process.cwd(), sha, releaseTargets) {
                 target,
             ])).values(),
         ].sort((a, b) => a.path.localeCompare(b.path));
+    const nextPending = releaseTargets === undefined
+        ? (existing[PENDING_RELEASE_TARGETS_KEY] ?? [])
+        : [...releaseTargets].sort((a, b) => a.path.localeCompare(b.path));
     const next = {
         [MANIFEST_VERSION_KEY]: 1,
         [BASELINE_SHA_KEY]: baselineShaValue,
         [RELEASE_TARGETS_KEY]: nextTargets,
+        [PENDING_RELEASE_TARGETS_KEY]: nextPending,
     };
     fs.writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
 }

package/dist/scm/github-plugin.js

@@ -99,14 +99,30 @@ function groupReleasesByIssue(releases) {
     }
     return new Map([...byIssue.entries()].sort(([a], [b]) => a - b));
 }
+const RELEASE_REFERENCE_COMMENT_FOOTER = "Released by [Versionary](https://github.com/jolars/versionary).";
 function renderReleaseLink(release) {
     if (release.name) {
         return `[\`${release.name}\` v${release.version}](${release.releaseUrl})`;
     }
     return `[version ${release.version}](${release.releaseUrl})`;
 }
+// Reads bodies of prior Versionary release-reference comments on an issue so we
+// can avoid re-announcing a release that has already been posted (e.g. when an
+// already-published target is re-processed on a later release run).
+async function readExistingReferenceComments(octokit, repo, issueNumber) {
+    const response = await octokit.issues.listComments({
+        owner: repo.owner,
+        repo: repo.repo,
+        issue_number: issueNumber,
+        per_page: 100,
+    });
+    return response.data
+        .map((comment) => comment.body ?? "")
+        .filter((body) => body.includes(RELEASE_REFERENCE_COMMENT_FOOTER))
+        .join("\n");
+}
 function renderReleaseReferenceCommentBody(releases) {
-    const footer = "Released by [Versionary](https://github.com/jolars/versionary).";
+    const footer = RELEASE_REFERENCE_COMMENT_FOOTER;
     if (releases.length === 1) {
         const release = releases[0];
         if (!release) {
@@ -312,7 +328,24 @@ export function createGitHubPlugin() {
             const releasesByIssue = groupReleasesByIssue(input.releases);
             const commented = [];
             for (const [reference, releases] of releasesByIssue) {
-                const body = renderReleaseReferenceCommentBody(releases);
+                let announcedText;
+                try {
+                    announcedText = await readExistingReferenceComments(octokit, repo, reference);
+                }
+                catch (error) {
+                    const { message } = parseGitHubError(error);
+                    if (mode === "strict") {
+                        throw new Error(`Failed listing existing comments on #${reference}: [${repoRef(repo)}] ${message}`);
+                    }
+                    context.logger?.warn(`Could not check existing comments on #${reference}, posting anyway: [${repoRef(repo)}] ${message}`);
+                    announcedText = "";
+                }
+                const pendingReleases = releases.filter((release) => !announcedText.includes(release.releaseUrl));
+                if (pendingReleases.length === 0) {
+                    context.logger?.info(`Skipping release reference comment on #${reference}: already announced.`);
+                    continue;
+                }
+                const body = renderReleaseReferenceCommentBody(pendingReleases);
                 try {
                     await octokit.issues.createComment({
                         owner: repo.owner,

package/dist/types/config.d.ts

@@ -33,6 +33,7 @@ export interface VersionaryConfig {
     "bump-minor-pre-major"?: boolean;
     "allow-stable-major"?: boolean;
     "include-commit-authors"?: boolean;
+    "exclude-paths"?: string[];
     "release-type"?: string | string[];
     packages?: Record<string, VersionaryPackage>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "versionary",
-  "version": "0.28.2",
+  "version": "0.30.0",
   "description": "Automatic release framework based on conventional commits and semantic versioning",
   "keywords": [
     "releasing",