gitflow-changesets-releases

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:

# 1. Create changeset file with descriptive name
cat > .changeset/descriptive-name.md << 'EOF'
---
"package-name": patch
---

Clear summary for CHANGELOG

- Optional bullet points for details
- Another detail
EOF

# 2. Commit
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
# ... make changes, commit ...
pnpm build && pnpm test:e2e

# Create changeset manually (recommended)
cat > .changeset/my-feature.md << 'EOF'
---
"package-name": patch
---

Add new feature description here
EOF

# Alternative: Interactive changeset
# pnpm changeset

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
# fix, then:
git commit -am "fix(scope): fix critical bug"

# Create changeset manually
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.