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.

gitflow-changesets-releases