diff --git a/.bumpy/readme-footer.md b/.bumpy/readme-footer.md
new file mode 100644
index 0000000..24c124f
--- /dev/null
+++ b/.bumpy/readme-footer.md
@@ -0,0 +1,5 @@
+---
+'@varlock/bumpy': patch
+---
+
+Use distinct frog image variants for different PR comment contexts and add Varlock links to README.
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..671a084
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,6 @@
+{
+ "attribution": {
+ "commit": "",
+ "pr": ""
+ }
+}
diff --git a/README.md b/README.md
index 21edadd..aa33f33 100644
--- a/README.md
+++ b/README.md
@@ -3,29 +3,30 @@
-
+
+Brought to you by Varlock 🧙♂️🔐 check it out to secure your secrets
# @varlock/bumpy 🐸
-A modern package versioning and changelog generation tool — built for monorepos (works great in single packages too).
+A modern package versioning, release, and changelog generation tool. Built for monorepos, but works great in simpler projects too.
## How It Works
-Bumpy uses **bump files** (you may know them as "changesets" if coming from [that tool 🦋](https://github.com/changesets/changesets)) — small markdown files that declare an intent to release packages with a bump level (patch/minor/major), and a description that ends up in changelogs. Developers create these files as part of their PRs, and these files are then used to consolidate changes, generate changelogs, and trigger publishing. Specifically:
+Bumpy uses **bump files** (you may know them as "changesets" if coming from [that tool 🦋](https://github.com/changesets/changesets)) - small markdown files that declare an intent to release packages with a bump level (patch/minor/major), and a description that ends up in changelogs. Developers create these files as part of their PRs, and these files are then used to consolidate changes, generate changelogs, and trigger publishing. Specifically:
- Devs/agents create bump files as part of their PRs (using `bumpy add` or manually)
- A pre-push git hook can enforce bump files exist for changed packages
- In CI, a workflow checks PRs for bump files, leaves a comment on the PR detailing changed packages
- As PRs merge to the base branch, a "release PR" is kept up to date
- Shows what packages will be released and their changelogs
- — Including packages bumped automatically due to dependency relationships
+ - 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
@@ -47,15 +48,15 @@ Fixed locale fallback logic in utils.
## Features
-- **All package managers** — npm, pnpm, yarn, and bun workspaces
-- **Smart dependency propagation** — configurable rules for how version bumps cascade through your dependency graph (see [version propagation docs](https://github.com/dmno-dev/bumpy/blob/main/docs/version-propagation.md))
-- **Pack-then-publish** — by default, publishes to npm (resolving `workspace:` and `catalog:` protocols, with OIDC/provenance support). Per-package custom publish commands let you target anything — VSCode extensions, Docker images, JSR, private registries, etc.
-- **Flexible package management** — include/exclude any package individually via per-package config, glob patterns, or `privatePackages` setting
-- **Non-interactive CLI** — `bumpy add` works fully non-interactively for CI/CD and AI-assisted development
-- **Aggregated GitHub releases** — optionally create a single consolidated release instead of one per package
-- **Auto-generate from commits** — `bumpy generate` creates bump files from branch commits — works with any commit style, with enhanced detection for conventional commits
-- **Pluggable changelog formatters** — built-in `"default"` and `"github"` formatters, or write your own
-- **Zero runtime dependencies** — dependencies are minimal and bundled at release time
+- **All package managers** - npm, pnpm, yarn, and bun workspaces
+- **Smart dependency propagation** - configurable rules for how version bumps cascade through your dependency graph (see [version propagation docs](https://github.com/dmno-dev/bumpy/blob/main/docs/version-propagation.md))
+- **Pack-then-publish** - by default, publishes to npm (resolving `workspace:` and `catalog:` protocols, with OIDC/provenance support). Per-package custom publish commands let you target anything - VSCode extensions, Docker images, JSR, private registries, etc.
+- **Flexible package management** - include/exclude any package individually via per-package config, glob patterns, or `privatePackages` setting
+- **Non-interactive CLI** - `bumpy add` works fully non-interactively for CI/CD and AI-assisted development
+- **Aggregated GitHub releases** - optionally create a single consolidated release instead of one per package
+- **Auto-generate from commits** - `bumpy generate` creates bump files from branch commits - works with any commit style, with enhanced detection for conventional commits
+- **Pluggable changelog formatters** - built-in `"default"` and `"github"` formatters, or write your own
+- **Zero runtime dependencies** - dependencies are minimal and bundled at release time
## Getting Started
@@ -77,10 +78,10 @@ Then set up CI to automate versioning and publishing (see below).
## CI / GitHub Actions
-No GitHub App to install, no separate action to rely on — just call `bumpy ci` directly in your workflows. Two commands handle the entire release lifecycle:
+No GitHub App to install, no separate action to rely on - just call `bumpy ci` directly in your workflows. Two commands handle the entire release lifecycle:
-- **`bumpy ci check`** — runs on every PR. Computes the release plan from pending bump files and posts/updates a comment on the PR showing what versions would be released. Warns if any changed packages are missing bump files.
-- **`bumpy ci release`** — runs on push to main. If pending bump files exist, it opens (or updates) a "Version Packages" PR that applies all version bumps and changelog updates. If the current push _is_ the Version Packages PR being merged, it publishes the new versions, creates git tags, and creates GitHub releases.
+- **`bumpy ci check`** - runs on every PR. Computes the release plan from pending bump files and posts/updates a comment on the PR showing what versions would be released. Warns if any changed packages are missing bump files.
+- **`bumpy ci release`** - runs on push to main. If pending bump files exist, it opens (or updates) a "Version Packages" PR that applies all version bumps and changelog updates. If the current push _is_ the Version Packages PR being merged, it publishes the new versions, creates git tags, and creates GitHub releases.
_examples use bun, but works with Node.js_
@@ -109,7 +110,7 @@ jobs:
### Release workflow
```yaml
-# .github/workflows/bumpy-release.yml — trusted publishing (OIDC, no secret needed)
+# .github/workflows/bumpy-release.yml - trusted publishing (OIDC, no secret needed)
name: Bumpy Release
on:
push:
@@ -137,13 +138,13 @@ jobs:
BUMPY_GH_TOKEN: ${{ secrets.BUMPY_GH_TOKEN }} # additonal 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.
+> **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.
Alternative: token-based auth (NPM_TOKEN secret)
```yaml
-# .github/workflows/bumpy-release.yml — token-based auth
+# .github/workflows/bumpy-release.yml - token-based auth
name: Bumpy Release
on:
push:
@@ -174,7 +175,7 @@ You can also use `bumpy ci release --auto-publish` to version + publish directly
### Token setup
-The default `github.token` works for basic functionality, but GitHub's anti-recursion guard means PRs created by the default token won't trigger other workflows — so your regular CI (tests, linting, etc.) won't run automatically on the Version Packages PR. To fix this, provide a `BUMPY_GH_TOKEN` secret using either a **fine-grained PAT** or a **GitHub App token**. See the [full token setup guide](https://github.com/dmno-dev/bumpy/blob/main/docs/github-actions.md#token-setup) for details.
+The default `github.token` works for basic functionality, but GitHub's anti-recursion guard means PRs created by the default token won't trigger other workflows - so your regular CI (tests, linting, etc.) won't run automatically on the Version Packages PR. To fix this, provide a `BUMPY_GH_TOKEN` secret using either a **fine-grained PAT** or a **GitHub App token**. See the [full token setup guide](https://github.com/dmno-dev/bumpy/blob/main/docs/github-actions.md#token-setup) for details.
Run `bumpy ci setup` for interactive guidance, or set it up manually:
@@ -210,30 +211,30 @@ bumpy ai setup --target cursor # creates Cursor rule file
bumpy ai setup --target codex # creates Codex instruction file
```
-The skill teaches the AI to examine git changes, identify affected packages, choose bump levels, and create bump files with `bumpy add`. It also instructs the AI to keep existing bump files up to date as work continues on a branch — updating packages, bump levels, and summaries to reflect the final state of changes.
+The skill teaches the AI to examine git changes, identify affected packages, choose bump levels, and create bump files with `bumpy add`. It also instructs the AI to keep existing bump files up to date as work continues on a branch - updating packages, bump levels, and summaries to reflect the final state of changes.
## Documentation
-- [Bump file format](https://github.com/dmno-dev/bumpy/blob/main/docs/bump-files.md) — syntax, bump levels, cascade control
-- [Configuration reference](https://github.com/dmno-dev/bumpy/blob/main/docs/configuration.md) — all `.bumpy/_config.json` and per-package options
-- [CLI reference](https://github.com/dmno-dev/bumpy/blob/main/docs/cli.md) — every command with flags and examples
-- [GitHub Actions setup](https://github.com/dmno-dev/bumpy/blob/main/docs/github-actions.md) — CI workflows, token setup, trusted publishing
-- [Version propagation](https://github.com/dmno-dev/bumpy/blob/main/docs/version-propagation.md) — how dependency bumps cascade through your graph
+- [Bump file format](https://github.com/dmno-dev/bumpy/blob/main/docs/bump-files.md) - syntax, bump levels, cascade control
+- [Configuration reference](https://github.com/dmno-dev/bumpy/blob/main/docs/configuration.md) - all `.bumpy/_config.json` and per-package options
+- [CLI reference](https://github.com/dmno-dev/bumpy/blob/main/docs/cli.md) - every command with flags and examples
+- [GitHub Actions setup](https://github.com/dmno-dev/bumpy/blob/main/docs/github-actions.md) - CI workflows, token setup, trusted publishing
+- [Version propagation](https://github.com/dmno-dev/bumpy/blob/main/docs/version-propagation.md) - how dependency bumps cascade through your graph
## Why files instead of conventional commits?
-Tools like semantic-release infer version bumps from commit messages (`feat:` → minor, `fix:` → patch). This works for simple projects but breaks down in monorepos — a single PR often touches multiple packages with different bump levels, squash merges lose per-commit metadata, and commit messages are a poor place to write user-facing changelog entries. Bump files are explicit, reviewable in the PR diff, and can describe changes in language meant for consumers rather than developers. If you prefer commit-based workflows, `bumpy generate` can bridge the gap by auto-creating bump files from your branch commits — it works with any commit style, not just conventional commits.
+Tools like semantic-release infer version bumps from commit messages (`feat:` → minor, `fix:` → patch). This works for simple projects but breaks down in monorepos - a single PR often touches multiple packages with different bump levels, squash merges lose per-commit metadata, and commit messages are a poor place to write user-facing changelog entries. Bump files are explicit, reviewable in the PR diff, and can describe changes in language meant for consumers rather than developers. If you prefer commit-based workflows, `bumpy generate` can bridge the gap by auto-creating bump files from your branch commits - it works with any commit style, not just conventional commits.
## Why not just use changesets?
-Bumpy is built as a successor to [@changesets/changesets](https://github.com/changesets/changesets). Changesets is mature and widely adopted, but has stagnated — hundreds of open issues around core design problems that are unlikely to be fixed without a rewrite. See [differences from changesets](https://github.com/dmno-dev/bumpy/blob/main/docs/differences-from-changesets.md) for a detailed comparison with links to specific issues. The biggest pain points bumpy addresses:
+Bumpy is built as a successor to [@changesets/changesets](https://github.com/changesets/changesets). Changesets is mature and widely adopted, but has stagnated - hundreds of open issues around core design problems that are unlikely to be fixed without a rewrite. See [differences from changesets](https://github.com/dmno-dev/bumpy/blob/main/docs/differences-from-changesets.md) for a detailed comparison with links to specific issues. The biggest pain points bumpy addresses:
-- **Sane dependency propagation** — changesets hardcodes aggressive behavior where a minor bump triggers a major bump on all peer dependents. Bumpy uses a [three-phase algorithm](https://github.com/dmno-dev/bumpy/blob/main/docs/version-propagation.md) with sensible defaults and full configurability.
-- **Workspace protocol resolution** — changesets uses `npm publish` even in pnpm/yarn workspaces, so `workspace:^` and `catalog:` protocols are NOT resolved, resulting in broken published packages.
-- **Custom publish commands** — changesets is hardcoded to `npm publish`. Bumpy supports per-package custom publish for VSCode extensions, Docker images, JSR, etc.
-- **Flexible package management** — changesets treats all private packages the same. Bumpy lets you include/exclude any package individually.
-- **CI without a separate action or bot** — changesets requires installing a [GitHub App](https://github.com/apps/changeset-bot) _and_ using a [separate GitHub Action](https://github.com/changesets/action). Bumpy replaces both with two CLI commands (`bumpy ci check` + `bumpy ci release`) that run directly in your workflows — no extra repos to trust, no app installation requiring org admin approval.
-- **Automatic migration** — `bumpy init` detects `.changeset/`, renames it to `.bumpy/`, migrates config, keeps pending files, and offers to uninstall `@changesets/cli`.
+- **Sane dependency propagation** - changesets hardcodes aggressive behavior where a minor bump triggers a major bump on all peer dependents. Bumpy uses a [three-phase algorithm](https://github.com/dmno-dev/bumpy/blob/main/docs/version-propagation.md) with sensible defaults and full configurability.
+- **Workspace protocol resolution** - changesets uses `npm publish` even in pnpm/yarn workspaces, so `workspace:^` and `catalog:` protocols are NOT resolved, resulting in broken published packages.
+- **Custom publish commands** - changesets is hardcoded to `npm publish`. Bumpy supports per-package custom publish for VSCode extensions, Docker images, JSR, etc.
+- **Flexible package management** - changesets treats all private packages the same. Bumpy lets you include/exclude any package individually.
+- **CI without a separate action or bot** - changesets requires installing a [GitHub App](https://github.com/apps/changeset-bot) _and_ using a [separate GitHub Action](https://github.com/changesets/action). Bumpy replaces both with two CLI commands (`bumpy ci check` + `bumpy ci release`) that run directly in your workflows - no extra repos to trust, no app installation requiring org admin approval.
+- **Automatic migration** - `bumpy init` detects `.changeset/`, renames it to `.bumpy/`, migrates config, keeps pending files, and offers to uninstall `@changesets/cli`.
## Development
@@ -253,4 +254,18 @@ bunx bumpy --help # invoke built cli
- Tracking workspace-level / non-publishable changes
- More frogs 🐸
+---
+
+
+
+ 
+
+
+
+ Bumpy is a creation of the team behind Varlock 🧙♂️
+
+ Check it out for secure secret sorcery - get your keys out of plaintext!
+
+
+
diff --git a/images/frog-clipboard.png b/images/frog-clipboard.png
new file mode 100644
index 0000000..b77834d
Binary files /dev/null and b/images/frog-clipboard.png differ
diff --git a/images/frog-error.png b/images/frog-error.png
new file mode 100644
index 0000000..ca8d4b1
Binary files /dev/null and b/images/frog-error.png differ
diff --git a/images/frog-neutral.png b/images/frog-neutral.png
index 5b7ac5b..cc3f5f3 100644
Binary files a/images/frog-neutral.png and b/images/frog-neutral.png differ
diff --git a/images/frog-warning.png b/images/frog-warning.png
new file mode 100644
index 0000000..58f3fa4
Binary files /dev/null and b/images/frog-warning.png differ
diff --git a/images/github-readme-footer.jpg b/images/github-readme-footer.jpg
new file mode 100644
index 0000000..d459fa0
Binary files /dev/null and b/images/github-readme-footer.jpg differ
diff --git a/packages/bumpy/src/commands/ci.ts b/packages/bumpy/src/commands/ci.ts
index d0c2534..dfad4e3 100644
--- a/packages/bumpy/src/commands/ci.ts
+++ b/packages/bumpy/src/commands/ci.ts
@@ -497,7 +497,7 @@ function formatReleasePlanComment(
const lines: string[] = [];
const preamble = [
- `
`,
+ `
`,
'',
'**The changes in this PR will be included in the next version bump.**',
'
',
@@ -575,7 +575,7 @@ function formatReleasePlanComment(
function formatBumpFileErrorsComment(errors: string[], prBranch: string | null, pm: PackageManager): string {
const runCmd = pmRunCommand(pm);
const lines = [
- `
`,
+ `
`,
'',
'**This PR has bump file(s) with errors that need to be fixed.**',
'
\n',
@@ -615,7 +615,7 @@ function formatEmptyBumpFileComment(): string {
function formatNoBumpFilesComment(prBranch: string | null, pm: PackageManager): string {
const runCmd = pmRunCommand(pm);
const lines = [
- ``,
+ `
`,
'',
"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',
diff --git a/packages/bumpy/src/types.ts b/packages/bumpy/src/types.ts
index 5f2f37f..0993fdd 100644
--- a/packages/bumpy/src/types.ts
+++ b/packages/bumpy/src/types.ts
@@ -156,7 +156,7 @@ export const DEFAULT_CONFIG: BumpyConfig = {
title: '🐸 Versioned release',
branch: 'bumpy/version-packages',
preamble: [
- `
`,
+ `
`,
'',
`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:`,
'
',