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

```bash
# 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**

```bash
# 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:**
```bash
git checkout main
git pull origin main
git checkout -b feature/shopping-cart
# Work, commit frequently, push every ~10 commits
```

**Switching between features:**
```bash
# 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:**
```bash
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