From 36d4f49fd74ba5ef05028bfb6a92c3d61ac23077 Mon Sep 17 00:00:00 2001 From: Theo Ephraim Date: Tue, 21 Apr 2026 12:24:49 -0700 Subject: [PATCH 1/3] Generate comprehensive README.md in .bumpy/ during init The init command now generates a detailed README explaining what bumpy is, how bump files work, and all the ways to create them (interactive, non-interactive, by hand, from conventional commits, empty). Commands are auto-detected to use the correct package manager runner (npx, bunx, pnpm, yarn). The README template lives in the repo's own .bumpy/ directory and is inlined at build time via tsdown's text loader. Co-Authored-By: Claude Opus 4.6 (1M context) --- .bumpy/README.md | 59 +++++++++++++++++++++++++++++ packages/bumpy/src/commands/init.ts | 18 ++++++--- packages/bumpy/src/globals.d.ts | 5 +++ packages/bumpy/tsdown.config.ts | 3 ++ 4 files changed, 80 insertions(+), 5 deletions(-) create mode 100644 .bumpy/README.md diff --git a/.bumpy/README.md b/.bumpy/README.md new file mode 100644 index 0000000..123afeb --- /dev/null +++ b/.bumpy/README.md @@ -0,0 +1,59 @@ +# 🐸 Bumpy + +This directory is used by [bumpy](https://bumpy.varlock.dev) to manage versioning and changelogs. + +Bumpy is a modern versioning tool for JavaScript/TypeScript projects (monorepos and single packages). It uses **bump files** — small markdown files in this directory — to declare pending version changes. These files are consumed during the release process to compute version bumps, update changelogs, and publish packages. + +## How it works + +1. When you make a change that should trigger a release, create a bump file (typically one per PR) +2. Bump files accumulate on your main branch until you're ready to release +3. At release time, bumpy merges all pending bumps into a release plan, updates versions and changelogs, and publishes packages + +## Creating bump files + +### Interactive + +```bash +bunx bumpy add +``` + +### Non-interactive (useful for AI-assisted development) + +```bash +bunx bumpy add --packages "package-name:minor,other-package:patch" --message "Description of changes" --name "my-change" +``` + +### By hand + +Create a `.md` file in this directory with YAML frontmatter mapping package names to bump levels (`major`, `minor`, or `patch`), and a markdown body for the changelog entry: + +```markdown +--- +'package-name': minor +--- + +Added a new feature. +``` + +### From conventional commits + +```bash +bunx bumpy generate +``` + +### Empty bump files + +For PRs that intentionally don't need a release (docs, CI, etc.): + +```bash +bunx bumpy add --empty --name "docs-update" +``` + +## Files in this directory + +- `_config.json` — bumpy configuration +- `README.md` — this file +- `*.md` (other than README.md) — pending bump files + +📖 Full documentation: https://bumpy.varlock.dev diff --git a/packages/bumpy/src/commands/init.ts b/packages/bumpy/src/commands/init.ts index 0f1c78a..15c887f 100644 --- a/packages/bumpy/src/commands/init.ts +++ b/packages/bumpy/src/commands/init.ts @@ -1,7 +1,16 @@ import { resolve } from 'node:path'; import { ensureDir, writeJson, writeText, exists } from '../utils/fs.ts'; import { log } from '../utils/logger.ts'; +import { detectPackageManager } from '../utils/package-manager.ts'; import type { BumpyConfig } from '../types.ts'; +import readmeTemplate from '../../../../.bumpy/README.md'; + +const PM_RUNNER: Record = { + bun: 'bunx bumpy', + pnpm: 'pnpm bumpy', + yarn: 'yarn bumpy', + npm: 'npx bumpy', +}; export async function initCommand(rootDir: string): Promise { const bumpyDir = resolve(rootDir, '.bumpy'); @@ -20,11 +29,10 @@ export async function initCommand(rootDir: string): Promise { }; await writeJson(resolve(bumpyDir, '_config.json'), config); - // Write a README explaining the directory - await writeText( - resolve(bumpyDir, 'README.md'), - `# 🐸 Bumpy\n\nThis directory is used by [bumpy](${__BUMPY_WEBSITE_URL__}) to manage versioning.\n\nBump files (\`.md\`) in this directory describe pending version bumps.\nRun \`bumpy add\` to create one interactively, or \`bumpy generate\` to auto-create from branch commits.\n`, - ); + // Write a README with commands tailored to the detected package manager + const pm = await detectPackageManager(rootDir); + const readmeContent = readmeTemplate.replaceAll('bunx bumpy', PM_RUNNER[pm] || 'npx bumpy'); + await writeText(resolve(bumpyDir, 'README.md'), readmeContent); log.success('Initialized .bumpy/ directory'); log.dim(' Created .bumpy/_config.json'); diff --git a/packages/bumpy/src/globals.d.ts b/packages/bumpy/src/globals.d.ts index 37a7c32..29980d7 100644 --- a/packages/bumpy/src/globals.d.ts +++ b/packages/bumpy/src/globals.d.ts @@ -13,3 +13,8 @@ declare const __BUMPY_VERSION__: string; * Injected at build time by tsdown, or via bunfig.toml when running from source * */ declare const __BUMPY_WEBSITE_URL__: string; + +declare module '*.md' { + const content: string; + export default content; +} diff --git a/packages/bumpy/tsdown.config.ts b/packages/bumpy/tsdown.config.ts index 1cac0bc..6688ea3 100644 --- a/packages/bumpy/tsdown.config.ts +++ b/packages/bumpy/tsdown.config.ts @@ -13,6 +13,9 @@ export default defineConfig({ format: 'esm', dts: true, clean: true, + loader: { + '.md': 'text', + }, define: { __BUMPY_VERSION__: JSON.stringify(pkg.version), __BUMPY_WEBSITE_URL__: JSON.stringify(ENV.BUMPY_WEBSITE_URL), From 040386c685ef08b66888a2fdf6b9dfaedb4298db Mon Sep 17 00:00:00 2001 From: Theo Ephraim Date: Tue, 21 Apr 2026 12:33:51 -0700 Subject: [PATCH 2/3] Add bump file for init README changes Co-Authored-By: Claude Opus 4.6 (1M context) --- .bumpy/init-readme.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .bumpy/init-readme.md diff --git a/.bumpy/init-readme.md b/.bumpy/init-readme.md new file mode 100644 index 0000000..3aca8e7 --- /dev/null +++ b/.bumpy/init-readme.md @@ -0,0 +1,5 @@ +--- +'@varlock/bumpy': patch +--- + +Generate comprehensive README.md in .bumpy/ during init with auto-detected package manager commands From 249c68c86f0cfd626578b0b1b68f9fd064c177e0 Mon Sep 17 00:00:00 2001 From: Theo Ephraim Date: Tue, 21 Apr 2026 12:54:26 -0700 Subject: [PATCH 3/3] Replace __BUMPY_WEBSITE_URL__ build-time var with hardcoded URL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No need for an env var / build-time injection — just hardcode https://bumpy.varlock.dev everywhere. Removes the varlock env definition, tsdown define, bunfig entry, and globals declaration. Co-Authored-By: Claude Opus 4.6 (1M context) --- .bumpy/README.md | 4 ++++ .env.schema | 2 +- packages/bumpy/bunfig.toml | 1 - packages/bumpy/src/cli.ts | 2 +- packages/bumpy/src/commands/ci.ts | 8 ++++---- packages/bumpy/src/globals.d.ts | 6 ------ packages/bumpy/src/types.ts | 4 ++-- packages/bumpy/tsdown.config.ts | 2 -- 8 files changed, 12 insertions(+), 17 deletions(-) diff --git a/.bumpy/README.md b/.bumpy/README.md index 123afeb..8325a9d 100644 --- a/.bumpy/README.md +++ b/.bumpy/README.md @@ -50,6 +50,10 @@ For PRs that intentionally don't need a release (docs, CI, etc.): bunx bumpy add --empty --name "docs-update" ``` +## Keeping bump files up to date + +As a PR evolves, make sure its bump file stays in sync. If the scope of changes grows (e.g., a patch becomes a new feature), update the bump level and description to match. Reviewers and AI assistants should treat the bump file as part of the PR — just like tests and docs. + ## Files in this directory - `_config.json` — bumpy configuration diff --git a/.env.schema b/.env.schema index 9b68591..2bf7a65 100644 --- a/.env.schema +++ b/.env.schema @@ -6,4 +6,4 @@ # Public URL for the bumpy website/docs # @type=url -BUMPY_WEBSITE_URL=https://github.com/dmno-dev/bumpy +BUMPY_WEBSITE_URL=https://bumpy.varlock.dev diff --git a/packages/bumpy/bunfig.toml b/packages/bumpy/bunfig.toml index 6e8d17b..3034047 100644 --- a/packages/bumpy/bunfig.toml +++ b/packages/bumpy/bunfig.toml @@ -3,4 +3,3 @@ [define] "__BUMPY_VERSION__" = "'dev'" -"__BUMPY_WEBSITE_URL__" = "'https://github.com/dmno-dev/bumpy'" diff --git a/packages/bumpy/src/cli.ts b/packages/bumpy/src/cli.ts index bc456d4..d28dbfa 100644 --- a/packages/bumpy/src/cli.ts +++ b/packages/bumpy/src/cli.ts @@ -234,7 +234,7 @@ function printHelp() { AI setup options: --target Target AI tool: opencode, cursor, codex - ${colorize(__BUMPY_WEBSITE_URL__, 'dim')} + ${colorize('https://bumpy.varlock.dev', 'dim')} `); } diff --git a/packages/bumpy/src/commands/ci.ts b/packages/bumpy/src/commands/ci.ts index 0113e80..81f27c2 100644 --- a/packages/bumpy/src/commands/ci.ts +++ b/packages/bumpy/src/commands/ci.ts @@ -435,7 +435,7 @@ function formatReleasePlanComment( const lines: string[] = []; const preamble = [ - `bumpy-frog`, + `bumpy-frog`, '', '**The changes in this PR will be included in the next version bump.**', '
', @@ -495,14 +495,14 @@ function formatReleasePlanComment( } lines.push('---'); - lines.push(`_This comment is maintained by [bumpy](${__BUMPY_WEBSITE_URL__})._`); + lines.push(`_This comment is maintained by [bumpy](https://bumpy.varlock.dev)._`); return lines.join('\n'); } function formatNoBumpFilesComment(prBranch: string | null, pm: PackageManager): string { const runCmd = pmRunCommand(pm); const lines = [ - `bumpy-frog`, + `bumpy-frog`, '', "Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. **If these changes should result in a version bump, you need to add a bump file.**", '
\n', @@ -519,7 +519,7 @@ function formatNoBumpFilesComment(prBranch: string | null, pm: PackageManager): } lines.push('\n---'); - lines.push(`_This comment is maintained by [bumpy](${__BUMPY_WEBSITE_URL__})._`); + lines.push(`_This comment is maintained by [bumpy](https://bumpy.varlock.dev)._`); return lines.join('\n'); } diff --git a/packages/bumpy/src/globals.d.ts b/packages/bumpy/src/globals.d.ts index 29980d7..f0f9e72 100644 --- a/packages/bumpy/src/globals.d.ts +++ b/packages/bumpy/src/globals.d.ts @@ -7,12 +7,6 @@ * Injected at build time by tsdown, or via bunfig.toml when running from source * */ declare const __BUMPY_VERSION__: string; -/** - * docs website url - * - * Injected at build time by tsdown, or via bunfig.toml when running from source - * */ -declare const __BUMPY_WEBSITE_URL__: string; declare module '*.md' { const content: string; diff --git a/packages/bumpy/src/types.ts b/packages/bumpy/src/types.ts index ed6a916..98b8466 100644 --- a/packages/bumpy/src/types.ts +++ b/packages/bumpy/src/types.ts @@ -144,9 +144,9 @@ export const DEFAULT_CONFIG: BumpyConfig = { title: '🐸 Versioned release', branch: 'bumpy/version-packages', preamble: [ - `bumpy-frog`, + `bumpy-frog`, '', - `This PR was created and will be kept in sync by [bumpy](${__BUMPY_WEBSITE_URL__}) based on your .bumpy bump files. Merge it when you are ready to release the packages listed below:`, + `This PR was created and will be kept in sync by [bumpy](https://bumpy.varlock.dev) based on your .bumpy bump files. Merge it when you are ready to release the packages listed below:`, '
', ].join('\n'), }, diff --git a/packages/bumpy/tsdown.config.ts b/packages/bumpy/tsdown.config.ts index 6688ea3..2852ee9 100644 --- a/packages/bumpy/tsdown.config.ts +++ b/packages/bumpy/tsdown.config.ts @@ -1,7 +1,6 @@ import { defineConfig } from 'tsdown'; import { readFileSync } from 'node:fs'; import 'varlock/auto-load'; -import { ENV } from 'varlock/env'; const pkg = JSON.parse(readFileSync('./package.json', 'utf-8')); @@ -18,6 +17,5 @@ export default defineConfig({ }, define: { __BUMPY_VERSION__: JSON.stringify(pkg.version), - __BUMPY_WEBSITE_URL__: JSON.stringify(ENV.BUMPY_WEBSITE_URL), }, });