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

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

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.