stack/docs/2-development/1-workflow/1-branching.md

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

# 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

# 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

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

git checkout -b refactor/auth-service-cleanup

docs/* — Documentation updates

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

git checkout -b docs/api-reference

Workflow

1. Start New Work

# 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

# 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

# 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

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

5. Create Pull Request

# 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

# 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

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:

# 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

# 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

# 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
• Commit Guidelines — Committing
• Database Migrations — Database