@williamthorsen/release-kit 13.0.0 → 13.1.0

package/.meta/changelog.json

@@ -1,4 +1,21 @@
 [
+  {
+    "version": "13.1.0",
+    "date": "2026-10-02",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Adds an `archived: true` mark to `repoLabels.labels` entries, which `sync-labels generate` writes to `.github/labels.yaml` without changing the output for unmarked labels. (#955)",
+            "hash": "23c0e0eeaf3e59cd921632850c7771ccdd6effe1",
+            "entry": 1
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "13.0.0",
     "date": "2026-10-01",

package/.readyup/kits/default.js

@@ -98,7 +98,7 @@ function translateGlob(pattern) {
 
 // .readyup/kits/default.ts
 function getMinVersion() {
-  const picked = { "version": "13.0.0" };
+  const picked = { "version": "13.1.0" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("release-kit/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -13,7 +13,7 @@
           "path": "kits/default.ts"
         },
         {
-          "hash": "7f9ab854",
+          "hash": "fd27a632",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -46,7 +46,7 @@
       "readyupVersion": "0.38.0",
       "source": "kits/default.ts",
       "sourceHash": "91bc3638",
-      "targetHash": "2fdeff1f"
+      "targetHash": "a3266cf2"
     },
     {
       "checklists": [

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## 13.1.0 — 2026-10-02
+
+### 🎉 Features
+
+- Adds an `archived: true` mark to `repoLabels.labels` entries, which `sync-labels generate` writes to `.github/labels.yaml` without changing the output for unmarked labels. (#955)
+
 ## 13.0.0 — 2026-10-01
 
 ### 🎉 Features

package/README.md

@@ -7,42 +7,11 @@ Version-bumping and changelog-generation toolkit for release workflows.
 Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs from the same commit history that decides each bump (with optional [editorial overrides](docs/editorial-overrides.md)).
 
 <!-- section:release-notes -->
-## Release notes — v13.0.0 (2026-10-01)
+## Release notes — v13.1.0 (2026-10-02)
 
 ### 🎉 Features
 
-- Adds the `--config <path>` flag to `release-kit push`, which now reads the config as `publish` and `create-github-release` do and fails when the file exists but is invalid. (#895)
-- Makes `release-kit` add an item derived from a change-record entry to a workspace's changelog and version bump only when the entry's `scopes`, after `scopeAliases` resolution, name the workspace's `dir`, are empty, or contain `*`, and extends that rule to the sections of earlier releases that `release-kit prepare` rebuilds. (#896)
-- Adds a warning to the `release-kit prepare` report that lists each change-record entry scope matching no workspace in its commit's window, such as a misspelled scope or the old name of a renamed directory that has no `scopeAliases` entry. (#896)
-- Makes `release-kit overrides validate` check a workspace's overrides against only the entries routed to that workspace, so that an override keyed to an entry routed elsewhere is reported as stale. (#896)
-- Adds `release-kit update-templates`, which writes each scaffolded workflow that is missing or differs from the installed template, prints a diff of each updated file, refreshes `sync-labels.yaml` only when it exists, keeps `publish.yaml`'s provenance setting, and never reads or writes the config files. (#952)
-- Changes the readyup kits' fix messages for a workflow that differs from its template, or that references a deprecated tag, to recommend `update-templates` rather than `init --force`. (#952)
-
-### 🪦 Removed
-
-- 🚨 **Breaking:** Removes `required` as a `breakingPolicies` value, making `drop` default to `optional` so that an unmarked `drop:` commit no longer reports a policy violation. (#905)
-- Stops `release-kit` from parsing a commit subject that combines a pipe scope with a parenthesized scope, such as `web|feat(other): ...`, or that lacks a space and a title after the colon, because subjects are now read through `@williamthorsen/change-grammar`. (#905)
-- Stops publishing `schemas/label-map.json` from `release-kit`, whose identical schema `@williamthorsen/change-grammar` now publishes; URLs under existing `release-kit-v*` tags keep resolving. (#905)
-
-### 🐛 Bug fixes
-
-- Record a changelog entry for a forced release whose commits yield no item (#887)
-
-  Makes `release-kit prepare` record the "Forced version bump." changelog entry for any release forced by `--force` or `--set-version` whose commits yield no changelog item, instead of only for a release with no commits at all. It also stops a monorepo's project release from dropping the forced-release entries that earlier releases recorded.
-
-- Stops `release-kit prepare` from reporting `commitCount` 0 and dropping the unparseable commits and change-record and policy diagnostics of a workspace released only because a dependency was bumped, and makes `prepare` list that workspace's commits in the release commit summary under its tag. (#888)
-- Stops `release-kit prepare` from labeling a direct release that has no commits as bumped via a dependency, by marking a propagation-only release with the new `propagatedOnly` result field, whose report line now reads `Bumped via dependency: …` in place of `0 commits (bumped via dependency: …)`. (#888)
-- Stops a `release-kit` command run from inside a package from releasing that package as a single-package repo with its own tag and changelog, by running every command from the repo root: the nearest directory that contains `pnpm-workspace.yaml`, or else the working directory when it contains a `package.json`. (#893)
-- Stops `sync-labels generate` from writing the `--config` path into the `.github/labels.yaml` header as typed, which made the header and the result of `generate --check` depend on the directory from which the command ran; the header now names the config by its path relative to the repo root. (#893)
-- Stops `push`, `publish`, and `create-github-release` from pushing, publishing, or creating a GitHub Release for a tag on HEAD whose workspace the config excludes with `shouldExclude: true`, which each command now skips with a warning, including when `--tags` names the tag or when every tag on HEAD is excluded. (#895)
-- Stops `release-kit prepare` from silently deleting a `CHANGELOG.md` section whose version is absent from both the release windows and `changelog.json`, such as history written by hand before release-kit was adopted; `prepare` now keeps that section verbatim in version order, lists the kept versions in its report, and warns about each `##` section that names no version and is dropped. (#897)
-- Stops `release-kit prepare` from folding every earlier commit into the new version, and deriving the bump from all of them, when the current version was released and recorded in the changelog but never tagged; `prepare` now fails before any write, under `--force` and `--set-version` too, and names each target and the tag to create. (#897)
-- Adds the missing `removal` and `formatting` labels to the `common` preset by defining a label for every work type in change-grammar's taxonomy, and keeps the names, colors, and descriptions of the existing type labels. (#906)
-- Fixes the `release.yaml` generated by `release-kit init`, which `actionlint` rejected because its `bump` choice input listed an empty string as the auto-detect option, by offering `auto` as the default option and passing it to the reusable release workflow as an empty `bump`. (#936)
-- Rewords the error messages, `prepare` report lines, command help, and readyup kit fix strings of `release-kit` that addressed the reader as "your", separated a detail from its subject with an em-dash, or stated an absence with "no", such as "No workspaces had release-worthy changes." (#937)
-- Fixes the issue that the `release.yaml` and `sync-labels.yaml` workflows generated by `release-kit init` and `release-kit sync-labels init` contained unclear wording in two comments and in the `force` input description, which the change rewrites without altering any job, trigger, or input; the release-kit kit check reports a copy generated before this change as stale until `release-kit init --force` or `release-kit sync-labels init --force` regenerates it. (#946)
-- Fixes the issue that `release-kit` titled a propagation-only bump's changelog section `Dependency updates` rather than with the resolved `deps` work type's header, `📦 Dependencies` by default or a consumer's `workTypes.deps.header` override, which broke the heading convention and left the section outside the section order. (#950)
-- Fixes the issue that `release-kit init`'s next steps told a public repo to set `provenance: true` in `publish.yaml`, which the template already sets, and now tells a private repo to remove it instead. (#952)
+- Adds an `archived: true` mark to `repoLabels.labels` entries, which `sync-labels generate` writes to `.github/labels.yaml` without changing the output for unmarked labels. (#955)
 <!-- /section:release-notes -->
 
 ## Installation

package/dist/esm/sync-labels/generateCommand.js

@@ -15,7 +15,12 @@ export function formatLabelsYaml(labels, presetHashes, configFilePath = CONFIG_F
     for (const [name, hash] of sortedPresetHashes) {
         headerLines.push(`# ${name} preset hash: ${hash}`);
     }
-    const declared = labels.map((label) => ({ ...label, description: label.description ?? '' }));
+    const declared = labels.map(({ archived, color, description, name }) => ({
+        name,
+        color,
+        description: description ?? '',
+        ...(archived !== undefined && { archived }),
+    }));
     const yamlBody = stringify(declared, { singleQuote: true, lineWidth: 0 });
     return headerLines.join('\n') + '\n' + yamlBody;
 }

package/dist/esm/sync-labels/resolveLabels.js

@@ -26,6 +26,7 @@ export function resolveLabels(config) {
                 name,
                 color: spec.color,
                 ...(spec.description !== undefined && { description: spec.description }),
+                ...(spec.archived !== undefined && { archived: spec.archived }),
             });
         }
     }

package/dist/esm/sync-labels/types.d.ts

@@ -1,4 +1,4 @@
-/** A single GitHub label definition compatible with EndBug/label-sync. */
+/** A single GitHub label definition, as `sync-labels generate` writes it to `.github/labels.yaml`. */
 export interface LabelDefinition {
     /** Display name of the label. */
     name: string;
@@ -6,4 +6,6 @@ export interface LabelDefinition {
     color: string;
     /** Short description shown in the GitHub UI. Absent when the label has none. */
     description?: string;
+    /** Marks the label for the sync to archive rather than keep active. Absent for an active label. */
+    archived?: true;
 }

package/dist/esm/types.d.ts

@@ -446,11 +446,13 @@ export declare const breakingPolicyValueSchema: z.ZodEnum<{
 export declare const labelSpecSchema: z.ZodObject<{
     color: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    archived: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strict>;
 /**
- * A label's color and optional description; the name is the record key in `repoLabels.labels`.
- * An omitted description resolves to empty, which the generated labels file declares explicitly so that a sync
- * clears whatever description the label has on the repo.
+ * A label's color, optional description, and optional archived mark; the name is the record key in
+ * `repoLabels.labels`. An omitted description resolves to empty, which the generated labels file declares explicitly
+ * so that a sync clears whatever description the label has on the repo. `archived: true` retires the label: The sync
+ * archives it, keeping it on the issues and pull requests that have it.
  */
 export type LabelSpec = z.infer<typeof labelSpecSchema>;
 /**
@@ -468,6 +470,7 @@ export declare const repoLabelsSchema: z.ZodObject<{
     labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
         color: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
+        archived: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strict>>>>;
 }, z.core.$strict>;
 /** Consumer-facing `repoLabels` block: bundled presets to extend plus per-name adjustments. */
@@ -496,6 +499,7 @@ export declare const releaseKitConfigSchema: z.ZodObject<{
         labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
             color: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
+            archived: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strict>>>>;
     }, z.core.$strict>>;
     retiredPackages: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/esm/types.js

@@ -55,6 +55,7 @@ export const labelSpecSchema = z
     .object({
     color: z.string().min(1),
     description: z.string().optional(),
+    archived: z.literal(true).optional(),
 })
     .strict();
 export const repoLabelsSchema = z

package/docs/labels.md

@@ -42,6 +42,20 @@ Names match case-insensitively, as GitHub matches them: `Bug` in the `labels` re
 
 Overlaps between layers are never errors; order resolves them, and the committed `.github/labels.yaml` diff shows any unexpected change at review. Two misstatements are config errors, because neither is visible in the output diff: a dangling `null`, which removes a name not defined by any preset, and `labels` keys that differ only in case, all but one of which the fold would discard.
 
+### Retiring a label
+
+Mark a label `archived: true` to retire it without losing its history:
+
+```typescript
+labels: {
+  'scope:basic': { color: '00ff96', archived: true }, // retire the scope of a removed package
+},
+```
+
+The sync workflow archives a marked label rather than deleting it. An archived label stays on the issues and pull requests that have it, but it cannot be added to new ones and does not appear in the label picker. Removing the mark unarchives the label on the next sync. Removing the entry instead deletes the label, as the sync deletes every label that `.github/labels.yaml` does not declare, and the label disappears from every issue and pull request that had it.
+
+The mark is set only in the `labels` record, not in a preset. To retire a preset's label, replace it with an entry that restates its color and adds the mark.
+
 ### When labels are applied
 
 The scaffolded workflow declares three triggers:
@@ -56,6 +70,8 @@ Applying on merge closes the window in which a regenerated `.github/labels.yaml`
 
 The `check` job runs the same sync in dry-run. Its **Label diff** log group lists every create, edit, rename, and deletion that the sync would perform, including deletions of labels that the file does not declare: the destructive edits that a diff of `.github/labels.yaml` alone cannot show, because a label created by hand or by another workflow is absent from the file both before and after. Read that log; the check reports success whether or not the diff is destructive, so a green check is not evidence that nothing will be deleted.
 
+Its **Archive state** log group lists each label that the sync would archive or unarchive. Archiving runs after the rest of the sync, so a label that the file both adds and marks is created and then archived.
+
 The two jobs are split because a job's permissions are fixed when the run is created and cannot vary by trigger. The split keeps a write-scoped token out of pull-request runs.
 
 The push trigger filters on the path alone; the `sync` job compares `github.ref_name` against the repository's default branch. The workflow therefore doesn't need a per-repo edit, whatever that branch is named, and a push touching `.github/labels.yaml` on any other branch produces a run whose jobs all skip.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "13.0.0",
+  "version": "13.1.0",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [
     "changelog",