Developer Workflow with Changesets

May contain stale references

This document was audited on 2026-06-22 and contains references that need updating: pdf-api and pdf-worker packages retired 2026-05-26. Cross-check critical details against the current codebase before relying on them.

This guide explains how to use changesets for version management and changelog generation in the ERP-Unlocked monorepo.

Table of Contents

• Overview
• Making Changes
• Creating a Changeset
• Checking Release Status
• Version Types
• Release Process
• Pre-commit Hook
• Troubleshooting

Overview

ERP-Unlocked uses Changesets to manage versions and changelogs across the monorepo. Each time you make a change to any app or package, you create a changeset that describes what changed and what type of change it is (major, minor, or patch).

Making Changes

The typical workflow for making changes:

1. Create a new branch for your feature/fix
2. Make your code changes
3. Before committing: Create a changeset
4. Commit both your changes and the changeset file
5. Push and create a pull request

Creating a Changeset

Step 1: Run the changeset command

After making your code changes, run:

pnpm changeset

Step 2: Select affected packages

The CLI will prompt you to select which packages have changed. Use the arrow keys and spacebar to select:

• @erp-unlocked/webapp - Main customer application
• @erp-unlocked/internal - Internal admin application
• @erp-unlocked/email-worker - Inbound email worker
• @erp-unlocked/pdf-api - PDF processing API
• @erp-unlocked/pdf-worker - PDF processing worker

Step 3: Choose the version bump type

For each selected package, choose the type of change:

• patch - Bug fixes and minor changes (0.1.0 → 0.1.1)
• minor - New features, backward compatible (0.1.0 → 0.2.0)
• major - Breaking changes (0.1.0 → 1.0.0)

Step 4: Write a summary

Provide a clear, concise summary of the changes. This will appear in the changelog:

Good Examples:

Fixed order validation to properly handle decimal quantities

Added support for custom tax rates in the order editor

BREAKING: Removed support for legacy CSV format

Bad Examples:

Fixed bug

Updated code

Step 5: Commit the changeset

The changeset will be saved to .changeset/random-words-here.md. Commit this file along with your code changes:

git add .changeset/random-words-here.md
git commit -m "feat: add custom tax rates support"

Checking Status

View pending releases

See what would be released based on current changesets:

pnpm version:check

Detailed view of pending releases

For more detailed information about what will change:

pnpm version:preview

Check if changesets exist

Verify that all necessary changesets are present:

pnpm changeset:status

Version Types

Changesets uses Semantic Versioning (SemVer):

Patch (0.1.0 → 0.1.1)

Use for:

• Bug fixes
• Documentation updates
• Internal refactoring
• Performance improvements

Example:

# Select: patch
# Summary: Fixed PDF extraction error for invoices with special characters

Minor (0.1.0 → 0.2.0)

Use for:

• New features
• New API endpoints
• Backward-compatible functionality additions
• UI enhancements

Example:

# Select: minor
# Summary: Added bulk order import feature with CSV upload

Major (0.1.0 → 1.0.0)

Use for:

• Breaking changes
• API changes that require client updates
• Removal of deprecated features
• Database schema changes

Example:

# Select: major
# Summary: BREAKING: Changed authentication to require organization context

Release Process (Maintainers Only)

Automated Release Flow

The repository uses a hybrid release strategy that balances speed and safety:

Staging Branch (Fully Automated)

1. When changes with changesets are pushed to staging
2. release.yml creates a “Version Packages” PR
3. The PR is automatically merged when all CI checks pass
4. Services are automatically deployed to staging

Timeline: ~10-15 minutes from push to deployment

This approach enables fast iteration and testing without manual intervention.

Main Branch (Manual Review)

1. When changes with changesets are pushed to main
2. release.yml creates a “Version Packages” PR
3. Maintainer manually reviews and merges the PR
4. Services are automatically deployed to production

Timeline: Controlled by maintainer approval

This approach ensures production releases are intentional and reviewed.

How It Works

Releases are automatically managed by GitHub Actions:

1. The release.yml workflow detects pending changesets
2. Creates a “Version Packages” pull request
3. When the PR is merged:
   • Updates package versions
   • Generates CHANGELOGs
   • Triggers Docker builds with semantic versions
   • Deploys to appropriate environment

Manual Release

If needed, maintainers can manually trigger releases:

# Step 1: Update versions based on changesets
pnpm version:apply

# Step 2: Install updated dependencies
pnpm install

# Step 3: Build all packages
pnpm build

# Step 4: Commit version changes
git add .
git commit -m "chore: version packages"
git push

# Step 5: Publish (handled by CI/CD)

Pre-commit Hook

The repository has a pre-commit hook that enforces changeset creation. If you try to commit changes to apps/ or packages/ without a changeset, you’ll see:

⚠️  Changes detected to apps/ or packages/ but no changeset found.

Please run: pnpm changeset
Then commit the generated changeset file.
Or skip with: git commit --no-verify

Skipping the hook

In rare cases where a changeset is not needed (e.g., CI config changes), you can skip the hook:

git commit --no-verify -m "ci: update workflow configuration"

Note: Use --no-verify sparingly. Most code changes should have a changeset.

Troubleshooting

”No packages selected” error

Make sure you’ve made changes to files in apps/ or packages/ directories. Changesets only tracks versioned packages.

Changeset file conflicts

If multiple developers create changesets simultaneously, you may encounter conflicts in changeset files. To resolve:

1. Keep both changeset files (they have unique names)
2. Don’t try to merge the content
3. Both changesets will be processed during release

Pre-commit hook issues

If the pre-commit hook is not working:

# Reinstall hooks
pnpm prepare

Changeset not detected in CI

Ensure the changeset file is committed and pushed:

git status
git add .changeset/*.md
git commit -m "chore: add changeset"
git push

Docker Image Versioning

When you create a changeset, the version bump will be used for Docker image tags:

• Development/PRs: Images tagged with pr-{commit-sha} (e.g., pr-a1b2c3d)
• Staging/Main: Images tagged with semantic version (e.g., 1.2.3)

Only services with changesets will have new Docker images built and deployed.

Examples

Example 1: Bug Fix in Webapp

# 1. Make the fix
# 2. Create changeset
pnpm changeset
# Select: @erp-unlocked/webapp
# Type: patch
# Summary: Fixed date formatting in order history

# 3. Commit
git add .
git commit -m "fix: correct date formatting in order history"
git push

Example 2: New Feature Across Multiple Apps

# 1. Implement feature in webapp and crm
# 2. Create changeset
pnpm changeset
# Select: @erp-unlocked/webapp, @erp-unlocked/crm
# Type: minor for both
# Summary: Added real-time order status updates with WebSocket support

# 3. Commit
git add .
git commit -m "feat: add real-time order status updates"
git push

Example 3: Breaking Change in PDF API

# 1. Make breaking changes to API
# 2. Create changeset
pnpm changeset
# Select: @erp-unlocked/pdf-api
# Type: major
# Summary: BREAKING: Changed /extract endpoint to require API version header

# 3. Commit
git add .
git commit -m "feat!: require API version in pdf-api endpoints"
git push

Best Practices

1. One changeset per logical change - Don’t combine unrelated changes
2. Write clear summaries - They become your changelog
3. Use conventional commit messages - Helps with PR organization
4. Create changesets early - Don’t wait until the PR is ready
5. Review changesets in PRs - Ensure accuracy before merging
6. Keep changesets focused - Smaller, focused changes are easier to review

Additional Resources

• Changesets Documentation
• Semantic Versioning
• Conventional Commits
• ERP-Unlocked Monorepo Guide

---

For questions or issues with the changeset workflow, please reach out to the maintainers or create an issue in the repository.