# Branching Strategy

Git workflow and branching conventions for Mosaic Stack.

## Branch Types

### Main Branches

**`main`** — Production-ready code only

- Never commit directly
- Only merge from `develop` via release
- Tagged with version numbers

**`develop`** — Active development (default branch)

- All features merge here first
- Must always build and pass tests
- Protected branch

### Supporting Branches

**`feature/*`** — New features

```bash
# From: develop
# Merge to: develop
# Naming: feature/issue-number-description

git checkout develop
git pull --rebase
git checkout -b feature/6-frontend-auth
```

**`fix/*`** — Bug fixes

```bash
# From: develop (or main for hotfixes)
# Merge to: develop (or both main and develop)
# Naming: fix/issue-number-description

git checkout develop
git checkout -b fix/12-session-timeout
```

**`refactor/*`** — Code improvements

```bash
# From: develop
# Merge to: develop
# Naming: refactor/area-description

git checkout -b refactor/auth-service-cleanup
```

**`docs/*`** — Documentation updates

```bash
# From: develop
# Merge to: develop
# Naming: docs/topic

git checkout -b docs/api-reference
```

## Workflow

### 1. Start New Work

```bash
# Always start from latest develop
git checkout develop
git pull --rebase

# Create feature branch
git checkout -b feature/7-task-management

# Optional: Use git worktree for parallel work
git worktree add ../mosaic-stack_worktrees/7-task-management -b feature/7-task-management
```

### 2. Make Changes

```bash
# Make changes, write tests first (TDD)
# Build and test after each change
pnpm test
pnpm build

# Commit frequently with conventional format
git add .
git commit -m "feat(#7): Add task creation endpoint"
```

### 3. Stay Updated

```bash
# Regularly sync with develop
git checkout develop
git pull --rebase
git checkout feature/7-task-management
git rebase develop

# Resolve conflicts if any
```

### 4. Push Changes

```bash
# Push feature branch
git push -u origin feature/7-task-management
```

### 5. Create Pull Request

```bash
# Use git.mosaicstack.dev web UI or
pr-create.sh -t "Implement task management" \
             -b "Adds full CRUD for tasks with tests" \
             -i 7

# Or with gh CLI
gh pr create --title "feat(#7): Implement task management" \
             --body "Full task management implementation..." \
             --base develop \
             --head feature/7-task-management
```

### 6. Code Review

- All PRs require review before merge
- Address review comments
- Keep commits clean (squash if messy)

### 7. Merge

```bash
# After approval, squash and merge
pr-merge.sh -n 7 -m squash -d

# Or via web UI: "Squash and Merge"
```

## Commit Message Format

```
<type>(#issue): Brief description

Detailed explanation if needed.

Fixes #123
```

### Types

- `feat` — New feature
- `fix` — Bug fix
- `docs` — Documentation
- `test` — Test additions/changes
- `refactor` — Code restructuring
- `chore` — Maintenance tasks
- `perf` — Performance improvements

### Examples

```bash
feat(#7): Add task creation endpoint

Implements POST /api/tasks with validation and tests.
Includes database migration for task table.

Fixes #7

---

fix(#12): Resolve session timeout issue

Sessions were expiring prematurely due to incorrect JWT config.
Updated JWT_EXPIRATION to use proper time format.

Fixes #12

---

docs(#15): Add API authentication guide

Complete guide for auth endpoints with examples.

Refs #15
```

## Protected Branch Rules

### `main` Branch

- No direct commits
- Require PR approval
- Require passing tests
- Require up-to-date branch

### `develop` Branch

- No direct commits (use PRs)
- Require passing tests
- Auto-delete head branches after merge

## Git Worktrees

For working on multiple issues simultaneously:

```bash
# Structure: {project_name}_worktrees/{issue-name}/
mkdir ~/src/mosaic-stack_worktrees

# Create worktree for issue #7
cd ~/src/mosaic-stack
git worktree add ../mosaic-stack_worktrees/7-task-management -b feature/7-task-management

# Work in worktree
cd ../mosaic-stack_worktrees/7-task-management
# Make changes, commit, push

# List worktrees
git worktree list

# Remove after merge
git worktree remove ../mosaic-stack_worktrees/7-task-management
```

## Best Practices

1. **Always start from `develop`**
2. **Keep branches short-lived** (max 1-2 weeks)
3. **Write tests first** (TDD approach)
4. **Commit frequently** with clear messages
5. **Rebase, don't merge** when syncing with develop
6. **Squash commits** before merging PR
7. **Delete branches** after merging
8. **Reference issues** in all commits

## Troubleshooting

### Conflicts During Rebase

```bash
# Start rebase
git rebase develop

# Conflicts occur
# Edit conflicting files

# Mark as resolved
git add <conflicted-files>
git rebase --continue

# Or abort and try later
git rebase --abort
```

### Accidentally Committed to `develop`

```bash
# Undo last commit (keep changes)
git reset --soft HEAD~1

# Create proper feature branch
git checkout -b feature/my-changes

# Commit again
git commit -m "feat: My changes"

# Force-push develop back to origin (if already pushed)
git checkout develop
git reset --hard origin/develop
git push --force
```

## Next Steps

- **Testing Requirements** — [Testing](2-testing.md)
- **Commit Guidelines** — [Committing](3-committing.md)
- **Database Migrations** — [Database](../2-database/2-migrations.md)