| name | gitflow-changesets-releases |
| description | Follow Gitflow with Changesets for branching, versioning, and releases. Manual changeset creation is recommended for reliability. Use when (1) creating or merging feature, release, or hotfix branches, (2) writing conventional commits, (3) adding or versioning changesets, (4) running tests before PR or release, or (5) the user asks about releases, changelog, branching, or gitflow. |
Git, Changesets and Versioning Workflow
Gitflow with Changesets for version management and releases. Branches: main (production), develop (integration), feat/* / fix/* (from develop), release/* (to main), hotfix/* (from main).
Branch Model
| Branch | Purpose | Created From | Merged To |
|---|
main | Production | - | release/*, hotfix/* |
develop | Integration | main | feat/*, fix/* |
feat/* | New features | develop | develop |
fix/* | Bug fixes | develop | develop |
release/* | Release preparation | develop | main, develop |
hotfix/* | Critical prod fixes | main | main, develop |
Manual Changeset Creation (Recommended)
Create changeset files manually for better control and reliability:
cat > .changeset/descriptive-name.md << 'EOF'
---
"package-name": patch
---
Clear summary for CHANGELOG
- Optional bullet points for details
- Another detail
EOF
git add .changeset/descriptive-name.md
git commit -m "chore: add changeset"
Format Template
---
"package-name": patch|minor|major
---
User-facing summary for CHANGELOG (use imperative: Add, Fix, Update)
- Optional: detailed bullet point
- Optional: another detail
Real Examples
Patch (Bug fix):
---
"einsan-landing": patch
---
Fix mobile menu button click handler for iOS devices
Patch with details:
---
"einsan-landing": patch
---
Optimize header and hero responsive design for better mobile experience
- Reduce header height across all breakpoints
- Add min-[375px] breakpoint for smoother logo scaling
- Improve navigation link readability with font-medium styling
Minor (New feature):
---
"einsan-landing": minor
---
Add dark mode toggle with system preference detection
Interactive Alternative: If you prefer prompts, run pnpm changeset (may hang on some systems).
Quick Workflows
Feature
Branch from develop → commit (conventional commits) → run pnpm build && pnpm test:e2e → create changeset (manual recommended) → commit changeset → push → PR to develop.
git checkout develop && git pull && git checkout -b feat/my-feature
pnpm build && pnpm test:e2e
cat > .changeset/my-feature.md << 'EOF'
---
"package-name": patch
---
Add new feature description here
EOF
git add .changeset/ && git commit -m "chore: add changeset"
git push -u origin feat/my-feature
Release
From develop: create release/vX.Y.Z → pnpm changeset:version → commit → run tests → merge to main → tag → back-merge to develop.
git checkout develop && git pull && git checkout -b release/v1.1.0
pnpm changeset:version
git add package.json CHANGELOG.md .changeset/ pnpm-workspace.yaml && git commit -m "chore: release v1.1.0"
pnpm build && pnpm test:e2e
git checkout main && git pull && git merge --no-ff release/v1.1.0
git tag -a v1.1.0 -m "Release v1.1.0" && git push origin main --tags
git checkout develop && git merge --no-ff release/v1.1.0 && git push origin develop
Hotfix
From main: create hotfix/name → fix → create changeset (manual) → pnpm changeset:version → run tests → merge to main → tag → back-merge to develop.
git checkout main && git pull && git checkout -b hotfix/critical-bug
git commit -am "fix(scope): fix critical bug"
cat > .changeset/critical-bug-fix.md << 'EOF'
---
"package-name": patch
---
Fix critical bug description
EOF
git add .changeset/ && git commit -m "chore: add changeset"
pnpm changeset:version
git add package.json CHANGELOG.md .changeset/ && git commit -m "chore: bump version for hotfix"
pnpm build && pnpm test:e2e
git checkout main && git merge --no-ff hotfix/critical-bug
git tag -a v1.1.1 -m "Hotfix v1.1.1" && git push origin main --tags
git checkout develop && git merge --no-ff hotfix/critical-bug && git push origin develop
Testing
Run before opening a PR and before merging release/hotfix to main:
pnpm build
pnpm test:e2e
Version Bumps
| Change type | Bump | Example |
|---|
| Breaking changes | major | 1.0.0 → 2.0.0 |
| New features | minor | 1.0.0 → 1.1.0 |
| Bug fixes | patch | 1.0.0 → 1.0.1 |
References
Load when needed for detailed steps, prompts, or troubleshooting:
-
Initial setup (first time)
See references/initial-setup.md for installing Changesets, config, and creating develop.
-
Feature development
See references/feature-development.md for full feature steps, commit types, and merge options.
-
Release process
See references/release-process.md for full release steps, staging, and fixing bugs on release branch.
-
Hotfix process
See references/hotfix-process.md for full hotfix steps.
-
Conventional commits
See references/conventional-commits.md for format, types, rules, and examples.
-
Changesets and testing
See references/changesets-testing.md for changeset prompts, file format, and when/how to run tests.
-
Best practices
See references/best-practices.md for branch, commit, changeset, and release guidelines.
-
Troubleshooting
See references/troubleshooting.md for changeset not found, version not updating, CHANGELOG, merge conflicts, wrong bump, tag exists.
