
# Git Workflow Guidelines for TinyTorch Development

## 🎯 **Core Principle: Dev-First Development**

**ALWAYS work in the `dev` branch.** Main branch is for stable releases only.

```yaml
git_workflow:
  default_branch: dev
  main_branch: stable releases only
  feature_branches: recommended for all changes
  commit_frequency: small and frequent
```

## 🌿 **Branch Strategy**

### **Main Branch (`main`)**
- **Release only**: Stable, tested code that's ready for public consumption
- **No direct commits**: Always merge from `dev`
- **Triggers deployment**: Pushes to main auto-deploy documentation

### **Dev Branch (`dev`)**
- **Default working branch**: Where all development happens
- **Always checkout dev first**: `git checkout dev` before starting work
- **Merge features here**: Test and validate before promoting to main

### **Feature Branches (Recommended)**
- **Create for any non-trivial change**: `git checkout -b feature/description`
- **Short-lived**: Merge back to dev quickly
- **Descriptive names**: `feature/visual-diagram`, `fix/faq-typos`, `docs/readme-update`

## 🔄 **Daily Workflow**

### **Starting Work**
```bash
# Always start from dev
git checkout dev
git pull origin dev

# Create feature branch for your work
git checkout -b feature/your-change-description
```

### **Making Changes**
```bash
# Make small, focused changes
git add .
git commit -m "TYPE: Brief description"

# Push feature branch
git push origin feature/your-change-description
```

### **Finishing Work**
```bash
# Merge to dev
git checkout dev
git merge feature/your-change-description

# Push dev
git push origin dev

# When ready for release, merge dev to main
git checkout main
git merge dev
git push origin main  # Triggers deployment
```

## 📝 **Commit Message Format**

```
TYPE: Brief description

- Bullet point of what changed
- Another change if needed

Examples:
- ADD: Visual waterfall diagram to README
- FIX: FAQ dropdown formatting
- REMOVE: Redundant FAQ section
- UPDATE: Module dependencies in workflow
```

## 🚨 **Rules to Follow**

1. **Never commit directly to main** - always go through dev
2. **Create feature branches** for anything beyond tiny fixes
3. **Start from dev branch** - `git checkout dev` first
4. **Test before merging** - make sure it works
5. **Small commits** - easy to revert if needed

## 🚀 **Quick Reference**

```bash
# Start any work session
git checkout dev
git pull origin dev
git checkout -b feature/my-change

# End any work session  
git checkout dev
git merge feature/my-change
git push origin dev
```

**Remember:** Dev branch is your playground, main branch is the published product.


**Remember:** It's better to have many small commits than one large commit that's hard to revert or understand.
