CTO/docs/GIT_WORKFLOW.MD

Git Workflow

This document outlines the git workflow for this repository, designed for use with Gitea.

Branch Structure

Main Branches

• main - The primary stable branch. Direct work should NOT be done on this branch.
• RELEASE - Production-ready code. Only accepts pull requests that have been manually reviewed and approved.
• INTEGRATION-WIP - Integration branch where all feature branches are automatically merged for testing and integration.

Feature Branches

• LLMBOOTSTRAP - Initial bootstrap feature branch for LLM-assisted development setup.
• Additional feature branches should follow naming conventions like feature/description or task/description.

Workflow Rules

1. Never work directly on main - All work must be done on feature branches.

2. Feature Development Flow:

   • Create feature branches from main
   • Develop features in isolation on these branches
   • Feature branches automatically merge to INTEGRATION-WIP for continuous integration testing

3. Integration Testing:

   • INTEGRATION-WIP branch serves as the integration environment
   • All feature branches are automatically merged here
   • Used for testing compatibility between different features

4. Release Process:

   • Only manually reviewed pull requests are merged to RELEASE
   • RELEASE branch represents production-ready code
   • Requires explicit approval before merging

Branch Protection

• main - Protected, no direct commits allowed
• RELEASE - Protected, only manual PR merges allowed
• INTEGRATION-WIP - Accepts automatic merges from feature branches

Feature Branch Management

CRITICAL: Branch Preservation

• NEVER automatically delete feature branches under any circumstances
• Feature branches must be preserved for historical reference and potential future work
• Branch deletion should only occur through explicit manual action after careful consideration

Commit and Push Frequency

• Commit frequently - Make small, logical commits as you work
• Push every 10 commits maximum - Don't let local commits accumulate
• ALWAYS push before switching branches - Ensure work is backed up remotely
• Push immediately before any branch operations (merge, rebase, etc.)

Tagging for Milestones

• Create tags when interim stages or milestones are completed
• Push tags immediately after creation to preserve milestone markers
• Tag naming conventions:
  • Date-based: milestone-YYYY-MM-DD or stage-YYYY-MM-DD-HHMM
  • Stage-based: bootstrap-complete, auth-module-done, integration-ready
  • Plan-based: Use milestone names from planning documents
• Always annotate tags with meaningful descriptions of what was accomplished

Best Practices

• Keep feature branches focused and small
• Use descriptive branch names
• Regularly sync feature branches with main
• Test thoroughly in INTEGRATION-WIP before requesting merge to RELEASE
• Write clear commit messages and PR descriptions
• Follow the commit/push frequency rules above

Examples: DO and DON'T

✅ DO Examples

# DO: Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/user-authentication

# DO: Commit frequently with descriptive messages
git add .
git commit -m "Add user login form validation"
git commit -m "Implement password hashing utility"
git commit -m "Add user session management"

# DO: Push after every 10 commits or before switching branches
git push origin feature/user-authentication

# DO: Push before switching to another branch
git push origin feature/user-authentication
git checkout feature/payment-system

# DO: Sync feature branch with main regularly
git checkout main
git pull origin main
git checkout feature/user-authentication
git merge main

# DO: Tag milestones with descriptive annotations
git tag -a bootstrap-complete -m "Initial project structure and workflow setup completed"
git push origin bootstrap-complete

# DO: Use date-based tags for interim stages
git tag -a stage-2025-09-05-1430 -m "Authentication module implementation complete"
git push origin stage-2025-09-05-1430

❌ DON'T Examples

# DON'T: Work directly on main
git checkout main
git add .
git commit -m "Fix user auth bug"  # ❌ NEVER DO THIS

# DON'T: Delete feature branches automatically
git branch -d feature/user-authentication  # ❌ NEVER DO THIS
git push origin --delete feature/user-authentication  # ❌ NEVER DO THIS

# DON'T: Let commits accumulate without pushing
git log --oneline  # Shows 15+ unpushed commits  # ❌ Should have pushed earlier

# DON'T: Switch branches without pushing current work
git checkout feature/payment-system  # ❌ Without pushing current branch first

# DON'T: Make massive commits
git add .
git commit -m "Complete entire user system"  # ❌ Too broad, break it down

# DON'T: Create tags without annotations
git tag milestone-1  # ❌ No description of what was accomplished
git push origin milestone-1

# DON'T: Forget to push tags
git tag -a bootstrap-complete -m "Setup complete"
# ❌ Missing: git push origin bootstrap-complete

🔧 Workflow Examples

Starting new feature:

git checkout main
git pull origin main
git checkout -b feature/shopping-cart
# Work, commit frequently, push every ~10 commits

Switching between features:

# Currently on feature/shopping-cart
git add .
git commit -m "Add item quantity validation"
git push origin feature/shopping-cart  # ✅ Push before switching
git checkout feature/user-profile

Preparing for integration:

git checkout feature/shopping-cart
git push origin feature/shopping-cart
# Feature automatically merges to INTEGRATION-WIP

Gitea Integration

This workflow is optimized for Gitea and utilizes:

• Branch protection rules
• Automatic merge capabilities for integration testing
• Manual review processes for production releases