---
slug: "gitflow-changesets-releases"
source_type: "skill_md"
source_url: "https://cdn.jsdelivr.net/gh/tevfikbgunes/gitflow-changesets-releases@main/SKILL.md"
repo: "https://github.com/tevfikbgunes/gitflow-changesets-releases"
source_file: "SKILL.md"
branch: "main"
---
---
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:

```bash
# 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

```markdown
---
"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):**
```markdown
---
"einsan-landing": patch
---

Fix mobile menu button click handler for iOS devices
```

**Patch with details:**
```markdown
---
"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):**
```markdown
---
"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`.

```bash
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`.

```bash
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`.

```bash
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`:

```bash
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](https://github.com/tevfikbgunes/gitflow-changesets-releases/blob/HEAD/references/initial-setup.md) for installing Changesets, config, and creating `develop`.

- **Feature development**  
  See [references/feature-development.md](https://github.com/tevfikbgunes/gitflow-changesets-releases/blob/HEAD/references/feature-development.md) for full feature steps, commit types, and merge options.

- **Release process**  
  See [references/release-process.md](https://github.com/tevfikbgunes/gitflow-changesets-releases/blob/HEAD/references/release-process.md) for full release steps, staging, and fixing bugs on release branch.

- **Hotfix process**  
  See [references/hotfix-process.md](https://github.com/tevfikbgunes/gitflow-changesets-releases/blob/HEAD/references/hotfix-process.md) for full hotfix steps.

- **Conventional commits**  
  See [references/conventional-commits.md](https://github.com/tevfikbgunes/gitflow-changesets-releases/blob/HEAD/references/conventional-commits.md) for format, types, rules, and examples.

- **Changesets and testing**  
  See [references/changesets-testing.md](https://github.com/tevfikbgunes/gitflow-changesets-releases/blob/HEAD/references/changesets-testing.md) for changeset prompts, file format, and when/how to run tests.

- **Best practices**  
  See [references/best-practices.md](https://github.com/tevfikbgunes/gitflow-changesets-releases/blob/HEAD/references/best-practices.md) for branch, commit, changeset, and release guidelines.

- **Troubleshooting**  
  See [references/troubleshooting.md](https://github.com/tevfikbgunes/gitflow-changesets-releases/blob/HEAD/references/troubleshooting.md) for changeset not found, version not updating, CHANGELOG, merge conflicts, wrong bump, tag exists.