pantry-app/pantry
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feature/issue-12-supabase-client
pantry/docs/BRANCHING.md
Claw f3ec382124
Some checks failed
Deploy to Coolify / Code Quality (push) Has been cancelled
Details
Deploy to Coolify / Run Tests (push) Has been cancelled
Details
Deploy to Coolify / Deploy to Development (push) Has been cancelled
Details
Deploy to Coolify / Deploy to Production (push) Has been cancelled
Details
Deploy to Coolify / Deploy to Test (push) Has been cancelled
Details
ci: Add Gitea Actions workflows and CI/CD documentation
2026-02-08 20:05:04 +00:00

7.1 KiB
Raw Permalink Blame History

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:

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:

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

# 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

# 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

# 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:

<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

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

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

Clean Commit History

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

# Squash WIP commits into logical commits

Tag Releases

# 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:

# 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.

Reference in New Issue View Git Blame Copy Permalink