pantry/docs/development/git-workflow.md

# Pantry - Branching Strategy

## 🌿 Branch Structure

```
main (production)
  ↑
  └── develop (development)
        ↑
        ├── feature/barcode-scanner
        ├── feature/tag-system
        ├── fix/quantity-bug
        └── chore/update-deps
```

---

## 📋 Branch Types

### `main` - Production

- **Purpose:** Production-ready code
- **Protection:** Require PR approval
- **Deploy:** Auto-deploy to production on push
- **Stability:** Must always be stable

**Rules:**
- Never commit directly
- Only merge from `develop` via release PR
- All merges must pass CI/CD checks

### `develop` - Development

- **Purpose:** Integration branch for features
- **Protection:** Require PR approval (optional)
- **Deploy:** Auto-deploy to dev environment on push
- **Stability:** Should be stable, but can have minor issues

**Rules:**
- Never commit directly (except hotfixes)
- Merge features via PR
- Keep in sync with `main` regularly

### `feature/*` - Features

- **Purpose:** New features or enhancements
- **Naming:** `feature/short-description`
- **Base:** Branch from `develop`
- **Merge:** PR to `develop`

**Examples:**
- `feature/barcode-scanner`
- `feature/tag-management`
- `feature/unit-conversions`

### `fix/*` - Bug Fixes

- **Purpose:** Fix bugs in `develop`
- **Naming:** `fix/short-description`
- **Base:** Branch from `develop`
- **Merge:** PR to `develop`

**Examples:**
- `fix/quantity-validation`
- `fix/tag-duplication`

### `hotfix/*` - Production Hotfixes

- **Purpose:** Critical fixes for production
- **Naming:** `hotfix/short-description`
- **Base:** Branch from `main`
- **Merge:** PR to both `main` AND `develop`

**Examples:**
- `hotfix/auth-bypass`
- `hotfix/data-corruption`

**Process:**
```bash
git checkout main
git pull
git checkout -b hotfix/critical-bug
# Fix bug
git push origin hotfix/critical-bug
# Create PR to main (deploy immediately)
# Create second PR to develop (keep in sync)
```

### `release/*` - Releases

- **Purpose:** Prepare for production release
- **Naming:** `release/v0.1.0`
- **Base:** Branch from `develop`
- **Merge:** PR to `main` (then tag)

**Process:**
```bash
git checkout develop
git pull
git checkout -b release/v0.1.0
# Update version, changelog, docs
git push origin release/v0.1.0
# Create PR to main
# After merge, tag main with v0.1.0
```

### `chore/*` - Maintenance

- **Purpose:** Dependencies, configs, tooling
- **Naming:** `chore/short-description`
- **Base:** Branch from `develop`
- **Merge:** PR to `develop`

**Examples:**
- `chore/update-nuxt`
- `chore/eslint-config`
- `chore/ci-improvements`

---

## 🔄 Workflow Examples

### Adding a Feature

```bash
# 1. Start from develop
git checkout develop
git pull origin develop

# 2. Create feature branch
git checkout -b feature/barcode-scanner

# 3. Work on feature
# ... make changes ...

# 4. Commit regularly
git add .
git commit -m "feat: Add barcode detection logic"

# 5. Push to remote
git push origin feature/barcode-scanner

# 6. Create PR to develop on Gitea
# Review → Merge → Auto-deploys to dev
```

### Releasing to Production

```bash
# 1. Ensure develop is stable
git checkout develop
git pull origin develop

# 2. Create release branch
git checkout -b release/v0.1.0

# 3. Update version and changelog
# Edit package.json, CHANGELOG.md

# 4. Commit and push
git commit -am "chore: Prepare v0.1.0 release"
git push origin release/v0.1.0

# 5. Create PR to main
# Review → Merge → Auto-deploys to production

# 6. Tag the release
git checkout main
git pull origin main
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

# 7. Merge back to develop (keep in sync)
git checkout develop
git merge main
git push origin develop
```

### Hotfix Production Issue

```bash
# 1. Branch from main
git checkout main
git pull origin main
git checkout -b hotfix/auth-bypass

# 2. Fix the issue
# ... fix ...

# 3. Commit and push
git commit -am "fix: Patch authentication bypass"
git push origin hotfix/auth-bypass

# 4. Create PR to main
# Urgent review → Merge → Immediate deploy

# 5. Also PR to develop (keep in sync)
git checkout develop
git pull origin develop
git checkout -b hotfix/auth-bypass-to-develop
git merge hotfix/auth-bypass
git push origin hotfix/auth-bypass-to-develop
# Create second PR to develop
```

---

## 📝 Commit Message Convention

Follow [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Types

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, no logic change)
- `refactor`: Code refactoring
- `test`: Adding/updating tests
- `chore`: Maintenance (deps, configs)
- `perf`: Performance improvement

### Examples

```bash
feat(scan): Add barcode scanner component
fix(inventory): Prevent negative quantities
docs(api): Update product lookup examples
chore(deps): Upgrade Nuxt to 4.1.2
refactor(tags): Simplify tag picker logic
test(units): Add conversion edge cases
```

---

## 🔒 Branch Protection Rules

### `main` (Production)

- ✅ Require pull request before merging
- ✅ Require status checks to pass
- ✅ Require review from code owner (1+)
- ✅ Dismiss stale approvals
- ❌ Allow force push
- ❌ Allow deletions

### `develop` (Development)

- ✅ Require pull request before merging (optional)
- ✅ Require status checks to pass
- ⚠️  Require review (recommended, not enforced)
- ❌ Allow force push
- ❌ Allow deletions

**Configure in Gitea:**
Repository → Settings → Branches → Add rule

---

## 🎯 Best Practices

### Keep Branches Short-Lived

- Feature branches: 1-3 days max
- Merge frequently to avoid conflicts
- Delete after merge

### Sync with Develop Regularly

```bash
# While on feature branch
git checkout feature/my-feature
git fetch origin
git merge origin/develop
# Resolve conflicts if any
```

### Clean Commit History

```bash
# Interactive rebase before PR (optional)
git rebase -i develop

# Squash WIP commits into logical commits
```

### Tag Releases

```bash
# After merging release to main
git checkout main
git pull
git tag -a v0.1.0 -m "MVP Release - Week 6"
git push origin v0.1.0
```

---

## 🚫 Anti-Patterns (Don't Do This)

❌ **Commit directly to `main`**
- Always use PR workflow

❌ **Long-lived feature branches**
- Break into smaller features
- Merge incrementally

❌ **Merge without review**
- At least one other person should review

❌ **Push broken code to `develop`**
- Test locally first
- CI checks should pass

❌ **Forget to sync hotfix to `develop`**
- Hotfixes must go to both branches

---

## 📊 Branch Lifecycle

```
feature/barcode-scanner
  Created: 2026-02-10
  Author: Jean-Luc
  Status: In Progress
  PRs: #15 (to develop)
  
  ↓ (PR merged)
  
  Merged to develop: 2026-02-12
  Deployed to dev: ✅
  Deleted: 2026-02-12
```

**Keep branches clean:**
```bash
# List merged branches
git branch --merged develop

# Delete merged local branches
git branch -d feature/barcode-scanner

# Delete merged remote branches
git push origin --delete feature/barcode-scanner
```

---

**Summary:** Keep it simple. Feature → PR → Develop → Test → Release → Main → Production. Always review, always test, never break `main`.