Merge pull request #50 from dmno-dev/docs/typos-and-fixes

Fix doc typos, add changelog formatter for GitHub releases

Author: theoephraim

.bumpy/docs-typos-and-fixes.md

@@ -0,0 +1,5 @@
+---
+'@varlock/bumpy': patch
+---
+
+Fix typos in docs/README, add claude to CLI help AI setup targets, and use changelog formatter for GitHub release bodies.

README.md

@@ -28,7 +28,7 @@ Bumpy uses **bump files** (you may know them as "changesets" if coming from [tha
   - Shows what packages will be released and their changelogs
     - Including packages bumped automatically due to dependency relationships
 - When release PR is merged, publishing is triggered
-  - Oending bump files are deleted and packages are published with updated versions and changelogs
+  - Pending bump files are deleted and packages are published with updated versions and changelogs
 
 All of this is automated via two simple GitHub Actions workflows (see [CI setup](#ci--github-actions) below). You can also run everything locally with `bumpy status`, `bumpy version`, and `bumpy publish`.
 
@@ -135,7 +135,7 @@ jobs:
       - run: bunx @varlock/bumpy ci release
         env:
           GH_TOKEN: ${{ github.token }}
-          BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} # additonal PAT, needed to trigger CI checks on release PR
+          BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} # additional PAT, needed to trigger CI checks on release PR
 ```
 
 > **Trusted publishing setup:** Configure each package on [npmjs.com](https://docs.npmjs.com/trusted-publishers/) → Package Settings → Trusted Publishers → GitHub Actions. Specify your org/user, repo, and the workflow filename (`bumpy-release.yml`). No `NPM_TOKEN` secret needed. Requires npm >= 11.5.1 - bumpy will warn if your version is too old.
@@ -240,7 +240,7 @@ Bumpy is built as a successor to [@changesets/changesets](https://github.com/cha
 
 ```bash
 bun install        # install deps
-bun test           # run tests
+bun run test       # run tests
 bun run build      # build CLI
 bunx bumpy --help  # invoke built cli
 ```

docs/changelog-formatters.md

@@ -8,7 +8,7 @@ There are several built-in formatters, or you can provide a custom function.
 
 ### `default`
 
-Simple markdown formatter. Produces a version heading, date, and bullet points from bump file summaries. _This is the default -- no settting required to enable_.
+Simple markdown formatter. Produces a version heading, date, and bullet points from bump file summaries. _This is the default -- no setting required to enable_.
 
 **Example output:**
 
@@ -98,23 +98,36 @@ interface ChangelogContext {
   bumpFiles: BumpFile[];
   /** ISO date string (YYYY-MM-DD) */
   date: string;
+  /** Where this entry will be used (default: 'changelog') */
+  target?: 'changelog' | 'github-release';
 }
 
 type ChangelogFormatter = (ctx: ChangelogContext) => string | Promise<string>;
 ```
 
+The `target` field tells your formatter where the output will be used:
+
+- `'changelog'` — writing to a `CHANGELOG.md` file (default)
+- `'github-release'` — creating a GitHub release body
+
+This lets you customize the output per context. For example, you might include full PR links in GitHub releases but keep changelog entries shorter, or omit the date sub-heading for GitHub releases since the release already has a timestamp.
+
 ### Example: custom formatter
 
 ```typescript
 import type { ChangelogFormatter } from '@varlock/bumpy';
 
 const formatter: ChangelogFormatter = (ctx) => {
-  const { release, bumpFiles, date } = ctx;
+  const { release, bumpFiles, date, target } = ctx;
   const lines: string[] = [];
   lines.push(`## ${release.newVersion}`);
   lines.push('');
-  lines.push(`_${date}_`);
-  lines.push('');
+
+  // Only include the date in changelog files — GitHub releases already show a date
+  if (target !== 'github-release') {
+    lines.push(`_${date}_`);
+    lines.push('');
+  }
 
   const relevantBumpFiles = bumpFiles.filter((bf) => release.bumpFiles.includes(bf.id));
 

docs/cli.md

@@ -1,6 +1,6 @@
 # CLI Reference
 
-All commands can be run via `bunx @varlock/bumpy <command>` or, (or just `bunx bumpy` if installed locally). Alternatively, you can invoke it via a package.json script (e.g., `bun run bumpy <command>`).
+All commands can be run via `bunx @varlock/bumpy <command>` (or just `bunx bumpy` if installed locally). Alternatively, you can invoke it via a package.json script (e.g., `bun run bumpy <command>`).
 
 ## `bumpy init`
 

packages/bumpy/src/cli.ts

@@ -233,7 +233,7 @@ function printHelp() {
     --branch <name>         Branch name for version PR (default: bumpy/version-packages)
 
   AI setup options:
-    --target <tool>         Target AI tool: opencode, cursor, codex
+    --target <tool>         Target AI tool: claude, opencode, cursor, codex
 
   ${colorize('https://bumpy.varlock.dev', 'dim')}
 `);

packages/bumpy/src/commands/publish.ts

@@ -5,6 +5,7 @@ import { DependencyGraph } from '../core/dep-graph.ts';
 import { pushWithTags, hasUncommittedChanges } from '../core/git.ts';
 import { publishPackages } from '../core/publish-pipeline.ts';
 import { createIndividualReleases, createAggregateRelease } from '../core/github-release.ts';
+import { loadFormatter } from '../core/changelog.ts';
 import { detectWorkspaces } from '../utils/package-manager.ts';
 import type { BumpyConfig, PackageConfig, ReleasePlan, PlannedRelease, WorkspacePackage } from '../types.ts';
 
@@ -108,14 +109,19 @@ export async function publishCommand(rootDir: string, opts: PublishCommandOption
     const isAggregate = aggConfig === true || (typeof aggConfig === 'object' && aggConfig.enabled);
     const aggTitle = typeof aggConfig === 'object' ? aggConfig.title : undefined;
 
+    // Load the changelog formatter so GitHub release bodies match CHANGELOG.md
+    const formatter = config.changelog !== false ? await loadFormatter(config.changelog, rootDir) : undefined;
+
     if (isAggregate) {
       await createAggregateRelease(publishedReleases, releasePlan.bumpFiles, rootDir, {
         dryRun: opts.dryRun,
         title: aggTitle,
+        formatter,
       });
     } else {
       await createIndividualReleases(publishedReleases, releasePlan.bumpFiles, rootDir, {
         dryRun: opts.dryRun,
+        formatter,
       });
     }
   }

packages/bumpy/src/core/changelog.ts

@@ -12,6 +12,8 @@ export interface ChangelogContext {
   bumpFiles: BumpFile[];
   /** ISO date string (YYYY-MM-DD) */
   date: string;
+  /** Where this entry will be used — formatters can customize output per target (default: 'changelog') */
+  target?: 'changelog' | 'github-release';
 }
 
 /**
@@ -159,8 +161,9 @@ export async function generateChangelogEntry(
   bumpFiles: BumpFile[],
   formatter: ChangelogFormatter = defaultFormatter,
   date: string = new Date().toISOString().split('T')[0]!,
+  target: ChangelogContext['target'] = 'changelog',
 ): Promise<string> {
-  return formatter({ release, bumpFiles, date });
+  return formatter({ release, bumpFiles, date, target });
 }
 
 /** Prepend a new entry to an existing CHANGELOG.md content */

packages/bumpy/src/core/github-release.ts

@@ -1,6 +1,8 @@
 import { tryRunArgs, runArgsAsync } from '../utils/shell.ts';
 import { log } from '../utils/logger.ts';
 import { listTags } from './git.ts';
+import { generateChangelogEntry } from './changelog.ts';
+import type { ChangelogFormatter } from './changelog.ts';
 import type { PlannedRelease, BumpFile } from '../types.ts';
 
 /** Get the current HEAD commit SHA */
@@ -11,6 +13,7 @@ function getHeadSha(rootDir: string): string | null {
 export interface GitHubReleaseOptions {
   dryRun?: boolean;
   title?: string;
+  formatter?: ChangelogFormatter;
 }
 
 /** Create individual GitHub releases for each published package */
@@ -29,7 +32,9 @@ export async function createIndividualReleases(
 
   for (const release of releases) {
     const tag = `${release.name}@${release.newVersion}`;
-    const body = buildReleaseBody(release, bumpFiles);
+    const body = opts.formatter
+      ? await generateReleaseBody(release, bumpFiles, opts.formatter)
+      : buildReleaseBody(release, bumpFiles);
     const title = `${release.name} v${release.newVersion}`;
 
     if (opts.dryRun) {
@@ -68,7 +73,9 @@ export async function createAggregateRelease(
   const date = new Date().toISOString().split('T')[0];
   const existing = listTags(`release-${date}*`, { cwd: rootDir });
   const { tag, title } = resolveAggregateTagAndTitle(date!, existing, opts.title);
-  const body = buildAggregateBody(releases, bumpFiles);
+  const body = opts.formatter
+    ? await generateAggregateBody(releases, bumpFiles, opts.formatter)
+    : buildAggregateBody(releases, bumpFiles);
 
   if (opts.dryRun) {
     log.dim(`  Would create aggregate GitHub release: ${title}`);
@@ -93,6 +100,62 @@ export async function createAggregateRelease(
   }
 }
 
+/** Generate a release body for a single package using the changelog formatter */
+async function generateReleaseBody(
+  release: PlannedRelease,
+  bumpFiles: BumpFile[],
+  formatter: ChangelogFormatter,
+): Promise<string> {
+  const entry = await generateChangelogEntry(release, bumpFiles, formatter, undefined, 'github-release');
+  // Strip the version heading — the GitHub release title already has the version
+  return stripVersionHeading(entry).trim() || 'No changelog entries.';
+}
+
+/** Generate an aggregate release body using the changelog formatter */
+async function generateAggregateBody(
+  releases: PlannedRelease[],
+  bumpFiles: BumpFile[],
+  formatter: ChangelogFormatter,
+): Promise<string> {
+  const lines: string[] = [];
+
+  // Group by bump type
+  const groups: [string, PlannedRelease[]][] = [
+    ['Major Changes', releases.filter((r) => r.type === 'major')],
+    ['Minor Changes', releases.filter((r) => r.type === 'minor')],
+    ['Patch Changes', releases.filter((r) => r.type === 'patch')],
+  ];
+
+  for (const [heading, group] of groups) {
+    if (group.length === 0) continue;
+    lines.push(`## ${heading}\n`);
+
+    for (const release of group) {
+      lines.push(`### ${release.name} v${release.newVersion}\n`);
+      const entry = await generateChangelogEntry(release, bumpFiles, formatter, undefined, 'github-release');
+      const body = stripVersionHeading(entry).trim();
+      if (body) {
+        lines.push(body);
+      } else if (release.isDependencyBump) {
+        lines.push('- Updated dependencies');
+      } else if (release.isCascadeBump) {
+        lines.push('- Version bump via cascade rule');
+      }
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n').trim() || 'No changelog entries.';
+}
+
+/** Strip the leading ## version heading and date sub-heading from a changelog entry */
+function stripVersionHeading(entry: string): string {
+  return entry
+    .replace(/^## .+\n/, '') // remove ## version heading
+    .replace(/^<sub>.+<\/sub>\n/, '') // remove <sub>date</sub> line
+    .replace(/^_.+_\n/, ''); // remove _date_ line
+}
+
 function buildReleaseBody(release: PlannedRelease, bumpFiles: BumpFile[]): string {
   const lines: string[] = [];
   const relevant = bumpFiles.filter((bf) => release.bumpFiles.includes(bf.id));

packages/bumpy/src/types.ts

@@ -156,7 +156,7 @@ export const DEFAULT_CONFIG: BumpyConfig = {
     title: '🐸 Versioned release',
     branch: 'bumpy/version-packages',
     preamble: [
-      `<a href="https://bumpy.varlock.dev"><img src="https://raw.githubusercontent.com/dmno-dev/bumpy/main/images/frog-party.png" alt="bumpy-frog" width="60" align="left" style="image-rendering: pixelated;" title="Hi! I'm bumpy!" /></a>`,
+      `<a href="https://bumpy.varlock.dev"><img src="https://raw.githubusercontent.com/dmno-dev/bumpy/main/images/frog-clipboard.png" alt="bumpy-frog" width="60" align="left" style="image-rendering: pixelated;" title="Hi! I'm bumpy!" /></a>`,
       '',
       `This PR was created and will be kept in sync by [bumpy](https://bumpy.varlock.dev) based on your bump files (in \`.bumpy/\`). Merge it when you are ready to release the packages listed below:`,
       '<br clear="left" />',