Skip to main content

​
Changesets

The BE Monorepo uses Changesets to manage versioning and changelogs across the monorepo packages.

​
What are Changesets?

Changesets is a tool for managing versions and changelogs in monorepos. It allows you to:
  • Track which packages have changes
  • Specify the type of change (major, minor, patch)
  • Write human-readable descriptions of changes
  • Automatically update versions and CHANGELOG.md files
  • Coordinate releases across multiple packages

​
Changeset Workflow

​
1. Make Code Changes

Develop your feature, bug fix, or other changes as usual: 
# Make your changes
edit apps/hono/src/routes/users.ts

# Test your changes
bun hono test
bun lint-typecheck

​
2. Create a Changeset

When your changes are ready, create a changeset: 
bun cs
Or use the full command: 
bun run changeset
This launches an interactive CLI that will ask:

​
Which packages would you like to include?

Select the packages that have changed: 
Which packages would you like to include?
✓ @workspace/hono
○ @workspace/core
○ @workspace/typescript-config

​
What kind of change is this?

For each selected package, specify the semantic version bump: 
What kind of change is this for @workspace/hono?
○ major – breaking changes
○ minor – new features, backwards compatible
● patch – bug fixes, minor improvements
Semantic versioning guide:
  • Major: Breaking changes that require user action
  • Minor: New features that are backwards compatible
  • Patch: Bug fixes and minor improvements

​
Summary

Provide a human-readable description of the changes: 
Summary: Add user profile endpoint with avatar upload support
This summary will appear in the CHANGELOG.md.

​
3. Review the Changeset

A new changeset file is created in .changeset/ directory: 
---
"@workspace/hono": patch
---

Add user profile endpoint with avatar upload support
Commit this file with your code changes: 
git add .changeset/
git commit -m "feat: add user profile endpoint"

​
4. Version the Changeset

When ready to release (typically after merging to main), version all pending changesets: 
bun cs:v
Or use the full command: 
bun run changeset version
This will:
  1. Update package versions in package.json files
  2. Update CHANGELOG.md files with changeset descriptions
  3. Remove consumed changesets from .changeset/ directory
  4. Update workspace dependencies to match new versions

​
5. Commit Version Changes

Commit the version bump and changelog updates: 
git add .
git commit -m "chore: version packages"
git push

​
Changeset Commands

​
bun cs

Create a new changeset interactively: 
bun cs
Alias for: changeset or changeset add

​
bun cs:v

Version packages based on pending changesets: 
bun cs:v
Alias for: changeset version

​
Advanced Commands

Other changeset commands (run with bunx changeset):

​
changeset status

Check which packages will be versioned: 
bunx changeset status

​
changeset publish

Publish packages to npm (if applicable): 
bunx changeset publish

​
Change Types and Semantic Versioning

​
Patch (0.0.X)

Bug fixes and minor improvements that don’t change the API:
  • Bug fixes
  • Performance improvements
  • Documentation updates
  • Dependency updates (non-breaking)
  • Refactoring (no API changes)

​
Minor (0.X.0)

New features that are backwards compatible:
  • New API endpoints
  • New functions/methods
  • New optional parameters
  • Feature enhancements
  • Deprecations (with backwards compatibility)

​
Major (X.0.0)

Breaking changes that require user action:
  • API changes that break existing code
  • Removed features/endpoints
  • Changed function signatures
  • Renamed exports
  • Major dependency upgrades with breaking changes

​
Best Practices

​
When to Create Changesets

✅ Do create changesets for:
  • New features
  • Bug fixes
  • API changes
  • Dependency updates
  • Performance improvements
❌ Don’t create changesets for:
  • Internal refactoring (no user impact)
  • Documentation-only changes (unless significant)
  • CI/config changes
  • Test updates

​
Writing Good Changeset Descriptions

✅ Good examples: 
Add user profile endpoint with avatar upload support
Fix rate limiting not applied to auth endpoints
Update Hono to v4.11.9 for performance improvements
❌ Bad examples: 
Updates
Fixes
Various improvements
Tips:
  • Start with a verb (Add, Fix, Update, Remove)
  • Be specific and concise
  • Mention user-facing impact
  • Reference issue numbers if applicable

​
Multiple Changesets

You can have multiple changesets pending: 
.changeset/
├── cool-pandas-smile.md
├── brave-lions-jump.md
└── README.md
All will be consumed when running bun cs:v.

​
Changeset in PRs

Include changesets in your pull requests:
  1. Make code changes
  2. Create changeset: bun cs
  3. Commit changeset with your changes
  4. Open pull request
  5. Changesets will be consumed when merged and released

​
Example Workflow

​
Complete Feature Development

# 1. Create feature branch
git checkout -b feat/user-profiles

# 2. Implement feature
edit apps/hono/src/routes/users.ts

# 3. Test changes
bun hono test
bun lint-typecheck

# 4. Create changeset
bun cs
# Select: @workspace/hono
# Type: minor
# Summary: Add user profile endpoint with avatar upload

# 5. Commit everything
git add .
git commit -m "feat: add user profile endpoint"

# 6. Push and create PR
git push origin feat/user-profiles

# After PR is merged to main:

# 7. Version packages
git checkout main
git pull
bun cs:v

# 8. Commit and push versions
git add .
git commit -m "chore: version packages"
git push

​
Upgrading Dependencies

# 1. Upgrade dependencies
bun bump:deps
bun install

# 2. Test changes
bun hono test
bun lint-typecheck

# 3. Create changeset
bun cs
# Select affected packages
# Type: patch (or major if breaking)
# Summary: Update dependencies to latest versions

# 4. Version and commit
bun cs:v
git add .
git commit -m "chore: upgrade dependencies"

​
Troubleshooting

​
No Changesets Detected

If bun cs:v reports no changesets:
  1. Check .changeset/ directory for changeset files
  2. Ensure changesets were committed
  3. Create a new changeset with bun cs

​
Version Not Updated

If package versions don’t update:
  1. Verify changeset file format is correct
  2. Ensure package names in frontmatter match package.json
  3. Check for YAML syntax errors in changeset

​
Merge Conflicts

If you encounter changeset merge conflicts:
  1. Keep both changeset files (they have unique names)
  2. Resolve CHANGELOG.md conflicts manually
  3. Run bun cs:v to regenerate changelog if needed

Build docs developers (and LLMs) love

Get started for freeTalk to us