Changesets CI/CD Migration - Implementation Summary

Status: ✅ Implementation Complete (Hybrid Approach Enabled) Date: 2025-10-11 (Initial) | 2025-10-12 (Hybrid Upgrade) Branch: staging

Quick Links

• Releasing Guide - How to use changesets
• Platform Architecture - Overall repository structure

What Was Implemented

1. Changesets Foundation ✅

Created:

• .changeset/config.json - Changesets configuration
• .changeset/README.md - Changesets documentation

Modified:

• package.json (root) - Added Changesets, Husky, lint-staged dependencies and scripts

Package Renaming:

• apps/webapp/package.json → @erp-unlocked/webapp
• apps/crm/package.json → @erp-unlocked/crm
• apps/marketing/package.json → @erp-unlocked/marketing

New Packages:

• apps/pdf-api/package.json → @erp-unlocked/pdf-api
• apps/pdf-worker/package.json → @erp-unlocked/pdf-worker

2. Pre-commit Hooks ✅

Created:

• .husky/pre-commit - Enforces changeset creation for app/package changes

Features:

• Runs lint-staged for code formatting
• Checks for changeset presence when apps/ or packages/ modified
• Skips check for merge commits
• Provides helpful error messages

3. Version-Aware CI/CD ✅

Created:

• .github/workflows/version-aware-build.yml - New conditional build pipeline
• .github/workflows/release.yml - Automated release management

Renamed:

• .github/workflows/ci-cd-pipeline.yml → ci-cd-pipeline-legacy.yml (backup)

Features:

• Detects version changes per service using Changesets
• Only builds Docker images for changed services
• Uses semantic versions for Docker tags (1.2.3 instead of staging-abc123)
• Supports PR builds with pr-{commit} tags
• Conditional deployments to staging and production
• Hybrid Release Strategy:
  • Staging: Auto-merge Version PRs for fast iteration
  • Production: Manual review for safety

4. Documentation ✅

Created:

• docs/DEVELOPER_WORKFLOW.md - Complete developer guide with examples
• docs/ci-cd-versioning-migration.md - Migration plan and timeline
• docs/CHANGESETS_IMPLEMENTATION_SUMMARY.md - This file

5. Hybrid Release Strategy ✅ (Updated 2025-10-12)

Modified:

• .github/workflows/release.yml - Upgraded to Option C Hybrid Approach

Changes:

1. Enable on Staging: Release workflow now runs on both main and staging branches
2. Fixed Changesets Action: Changed from publish parameter to version parameter with createGithubReleases: false
3. Auto-Merge for Staging: Added auto-merge-staging job that automatically merges Version PRs on staging branch
4. PR Number Output: Release job now outputs the PR number for downstream jobs

Behavior:

• Staging Branch: Version PRs are automatically merged when all CI checks pass (fast iteration)
• Main Branch: Version PRs require manual review before merge (production safety)

New Commands Available

For Developers

# Create a changeset (run after making changes)
pnpm changeset

# Check what would be released
pnpm version:check

# Detailed view of pending releases
pnpm version:preview

For Maintainers

# Apply version changes from changesets
pnpm version:apply

# Prepare for release (version + install)
pnpm release:prepare

# Publish packages (automated via CI)
pnpm release:publish

How It Works

Developer Flow

1. Make Changes - Modify code in any app or package
2. Create Changeset - Run pnpm changeset before committing
3. Select Packages - Choose which apps/packages changed
4. Choose Version - Select patch/minor/major bump
5. Write Summary - Describe the changes (becomes changelog)
6. Commit - Commit both code and changeset file
7. Push PR - Create pull request to staging

PR Build Flow

1. PR opened/updated triggers version-aware-build.yml
2. Detects which apps have file changes
3. Builds Docker images only for changed apps
4. Tags images with pr-{commit-sha} format
5. Does NOT deploy (build only for validation)

Release Flow (Staging/Main)

1. PR merged to staging or main
2. version-aware-build.yml detects changeset-based versions
3. Builds Docker images with semantic version tags (1.2.3)
4. Pushes images to GHCR
5. Deploys to appropriate environment (staging/production)
6. Only changed services are built and deployed

Automated Release (Hybrid Approach)

Staging Branch (Fully Automated):

1. Changesets detected on staging branch
2. release.yml creates “Version Packages” PR
3. auto-merge-staging job automatically enables auto-merge
4. PR merges automatically when all CI checks pass
5. Triggers new build with updated versions
6. Services auto-deploy to staging

Timeline: ~10-15 minutes from push to deployment

Main Branch (Manual Review):

1. Changesets detected on main branch
2. release.yml creates “Version Packages” PR
3. Maintainer manually reviews the Version PR
4. When manually merged, triggers new build with updated versions
5. Services auto-deploy to production

Timeline: Controlled by maintainer approval

File Structure Changes

erp-unlocked/
├── .changeset/                         # NEW
│   ├── config.json                    # Changesets config
│   └── README.md                      # Changesets docs
├── .github/
│   ├── workflows/
│   │   ├── version-aware-build.yml    # NEW - Main CI/CD
│   │   └── release.yml                # NEW - Automated releases
│   └── workflows-backup/
│       └── ci-cd-pipeline-legacy.yml  # MOVED - Backup (disabled)
├── .husky/
│   └── pre-commit                     # NEW - Changeset enforcement
├── apps/
│   ├── webapp/
│   │   └── package.json               # MODIFIED - Renamed @erp-unlocked/webapp
│   ├── crm/
│   │   └── package.json               # MODIFIED - Renamed @erp-unlocked/crm
│   ├── marketing/
│   │   └── package.json               # MODIFIED - Renamed @erp-unlocked/marketing
│   ├── pdf-api/
│   │   └── package.json               # NEW - Enables versioning
│   └── pdf-worker/
│       └── package.json               # NEW - Enables versioning
├── docs/
│   ├── DEVELOPER_WORKFLOW.md          # NEW - Developer guide
│   ├── ci-cd-versioning-migration.md  # NEW - Migration plan
│   └── CHANGESETS_IMPLEMENTATION_SUMMARY.md  # NEW - This file
└── package.json                        # MODIFIED - Added dependencies

Breaking Changes

For Developers

1. Changesets Required - Must run pnpm changeset before committing app/package changes
2. Pre-commit Hook - Blocks commits without changeset (can skip with --no-verify)
3. Package Names - Internal package names changed (shouldn’t affect workflows)

For CI/CD

1. New Workflow - version-aware-build.yml replaces ci-cd-pipeline.yml
2. Docker Tags - Semantic versions (1.2.3) instead of git-based (staging-abc123)
3. Conditional Builds - Only changed services built (faster, more efficient)

Expected Benefits

CI/CD Efficiency

• Before: ~15 minutes to build all 5 services
• After: ~5-10 minutes to build 1-2 changed services
• Savings: 50-75% reduction in build time

Developer Experience

• Automated Changelogs - No manual CHANGELOG.md updates
• Clear Versioning - Semantic versions convey change magnitude
• Enforced Documentation - Pre-commit hook ensures change tracking

Operational

• Selective Deployments - Only deploy what changed
• Version Traceability - Clear mapping of version → changes
• Faster Releases - Automated version bumping and changelog generation

Testing Checklist

Before considering migration complete, verify:

• Changeset creation works (pnpm changeset)
• Pre-commit hook blocks commits without changeset
• Pre-commit hook allows bypass with --no-verify
• PR builds detect changed apps correctly
• PR builds tag images with pr-{sha} format
• Staging builds use semantic versions from changesets
• Only changed services build on staging
• Staging deployments work correctly
• Release workflow creates “Version Packages” PR on main
• Production builds use correct semantic versions
• Production deployments work correctly

Rollback Instructions

If issues arise, follow these steps:

1. Quick Rollback (Restore Old CI/CD)

# Restore old pipeline
mv .github/workflows/ci-cd-pipeline-legacy.yml .github/workflows/ci-cd-pipeline.yml
mv .github/workflows/version-aware-build.yml .github/workflows/version-aware-build-disabled.yml

# Disable pre-commit hook
mv .husky/pre-commit .husky/pre-commit.disabled

# Commit and push
git add .github/workflows/ .husky/
git commit -m "rollback: restore legacy CI/CD pipeline"
git push

2. Full Rollback (Remove All Changes)

The migration is complete; this rollback plan is retained for historical reference.

Next Steps

Immediate (Testing Phase)

1. Create test PR with changeset on staging
2. Verify build and deployment workflow
3. Document any issues or improvements

Short-term (Week 1-2)

1. Train team on changeset workflow
2. Monitor CI/CD performance metrics
3. Gather team feedback
4. Make adjustments as needed

Medium-term (Week 3-4)

1. Deploy to production after successful staging testing
2. Remove legacy CI/CD pipeline
3. Update all repository documentation
4. Establish changeset best practices

Long-term (Month 2+)

1. Review changelog quality
2. Optimize version bump strategy
3. Consider automated semantic release
4. Evaluate additional automation opportunities

Support and Resources

Getting Help

1. Check Releasing Guide for usage questions
2. Review Changesets Documentation for migration questions
3. Ask in team channels or create repository issues

Key Concepts

• Changeset - A file describing changes to one or more packages
• Semantic Versioning - Version format MAJOR.MINOR.PATCH (1.2.3)
• Version Bump - Incrementing version based on change type
• Changelog - Auto-generated list of changes per version

Common Issues

“No packages selected” error

• Ensure changes are in apps/ or packages/ directories
• Check that package has private: false in package.json

Pre-commit hook blocking commit

• Run pnpm changeset to create changeset
• Or skip with git commit --no-verify (use sparingly)

Changeset not detected in CI

• Ensure changeset file is committed and pushed
• Check .changeset/ directory contains .md files

Docker build not triggered

• Verify changeset exists for the specific service
• Check GitHub Actions logs for version detection output

Success Metrics

Track these to measure implementation success:

Technical Metrics

• CI/CD build time reduced by 50%+
• Only changed services built per commit
• 100% of releases have proper semantic versions
• Zero manual changelog updates needed

Process Metrics

• 100% changeset compliance (via pre-commit hook)
• < 2 minutes to create changeset
• < 5% pre-commit hook bypasses
• Zero version-related deployment issues

Team Metrics

• All developers trained on changeset workflow
• Positive team feedback on new process
• Reduced time spent on release management
• Improved changelog quality

Additional Notes

Python Services (pdf-api, pdf-worker)

The Python services now have package.json files to enable Changesets tracking. The version script updates the version in pyproject.toml when changesets are applied:

# When changeset version is run, it also updates:
apps/pdf-api/pyproject.toml - [project] version field
apps/pdf-worker/pyproject.toml - [project] version field

Docker Image Versioning

Docker images now use semantic versions:

Before:

ghcr.io/dboone31/erp-unlocked/webapp:staging-a1b2c3d
ghcr.io/dboone31/erp-unlocked/webapp:main-b4c5d6e

After:

ghcr.io/dboone31/erp-unlocked/webapp:1.2.3
ghcr.io/dboone31/erp-unlocked/webapp:latest
ghcr.io/dboone31/erp-unlocked/webapp:pr-a1b2c3d (for PRs)

Workspace Configuration

The workspace is now configured to track 5 versioned applications:

1. @erp-unlocked/webapp - Main customer application
2. @erp-unlocked/crm - CRM application
3. @erp-unlocked/marketing - Marketing website
4. @erp-unlocked/pdf-api - PDF processing API
5. @erp-unlocked/pdf-worker - PDF processing worker

Shared packages (@repo/*) are ignored from versioning as specified in .changeset/config.json.

---

Implementation Date: 2025-10-11
Status: ✅ Complete - Ready for Testing
Next Review: After staging deployment testing
Maintainers: Development Team