# Git Workflow Guide

How to manage branches, commits, and pull requests for OpenNoodl development.

## Branch Naming

### Format

```
type/id-short-description
```

### Types

| Type | Use For | Example |
|------|---------|---------|
| `task` | Task documentation work | `task/001-dependency-updates` |
| `feature` | New features | `feature/vercel-deployment` |
| `fix` | Bug fixes | `fix/page-router-scroll` |
| `refactor` | Code improvements | `refactor/property-panel-hooks` |
| `docs` | Documentation only | `docs/api-reference` |
| `test` | Test additions | `test/rest-node-coverage` |

### Examples

```bash
# Task branches (from dev-docs)
git checkout -b task/001-dependency-updates
git checkout -b task/002-typescript-cleanup

# Feature branches
git checkout -b feature/add-oauth-support
git checkout -b feature/multi-project-windows

# Fix branches
git checkout -b fix/nested-router-scroll
git checkout -b fix/array-change-tracking

# Refactor branches
git checkout -b refactor/remove-class-components
git checkout -b refactor/data-node-architecture
```

## Commit Messages

### Format

```
type(scope): short description

[optional longer description]

[optional footer with references]
```

### Types

- `feat` - New feature
- `fix` - Bug fix
- `refactor` - Code restructuring (no behavior change)
- `docs` - Documentation changes
- `test` - Test additions/changes
- `chore` - Build/tooling changes
- `style` - Formatting (no code change)
- `perf` - Performance improvement

### Scopes

Use the affected area:

- `editor` - Main editor code
- `runtime` - Runtime engine
- `viewer` - Viewer/preview
- `ui` - Core UI components
- `build` - Build system
- `deps` - Dependencies

### Examples

```bash
# Features
git commit -m "feat(editor): add connection breakpoints"
git commit -m "feat(runtime): implement retry logic for REST node"

# Fixes
git commit -m "fix(viewer): resolve scroll jumping in nested routers"
git commit -m "fix(editor): prevent crash when deleting connected node"

# Refactoring
git commit -m "refactor(ui): convert PropertyPanel to functional component"
git commit -m "refactor(runtime): simplify collection change tracking"

# Docs
git commit -m "docs(readme): update installation instructions"
git commit -m "docs(api): add JSDoc to public methods"

# Tests
git commit -m "test(runtime): add unit tests for REST node"
git commit -m "test(editor): add integration tests for import flow"

# Chores
git commit -m "chore(deps): update webpack to 5.101.3"
git commit -m "chore(build): enable source maps in development"
```

### Multi-line Commits

For complex changes:

```bash
git commit -m "feat(editor): add AI-powered node suggestions

- Integrate with OpenAI API for code analysis
- Add suggestion UI in node picker
- Cache suggestions for performance

Closes #123"
```

## Workflow

### Starting Work

```bash
# 1. Ensure main is up to date
git checkout main
git pull origin main

# 2. Create your branch
git checkout -b task/001-dependency-updates

# 3. Make your changes...

# 4. Stage and commit frequently
git add -A
git commit -m "feat(deps): update React to v19"
```

### During Development

```bash
# Check status often
git status

# View your changes
git diff

# Stage specific files
git add packages/noodl-editor/package.json

# Commit logical chunks
git commit -m "fix(deps): resolve peer dependency conflicts"

# Push to remote (first time)
git push -u origin task/001-dependency-updates

# Push subsequent commits
git push
```

### Keeping Up to Date

```bash
# If main has changed, rebase your work
git fetch origin
git rebase origin/main

# Resolve any conflicts, then continue
git add .
git rebase --continue

# Force push after rebase (your branch only!)
git push --force-with-lease
```

### Creating Pull Request

1. Push your branch to remote
2. Go to GitHub repository
3. Click "New Pull Request"
4. Select your branch
5. Fill in the template:

```markdown
## Summary
Brief description of changes

## Task Reference
TASK-001: Dependency Updates

## Changes Made
- Updated React to v19
- Fixed peer dependency conflicts
- Migrated to createRoot API

## Testing
- [ ] All existing tests pass
- [ ] Manual testing completed
- [ ] New tests added (if applicable)

## Checklist
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] No console.log statements
```

### After PR Merged

```bash
# Switch to main
git checkout main

# Pull the merged changes
git pull origin main

# Delete your local branch
git branch -d task/001-dependency-updates

# Delete remote branch (if not auto-deleted)
git push origin --delete task/001-dependency-updates
```

## Common Scenarios

### Oops, Wrong Branch

```bash
# Stash your changes
git stash

# Switch to correct branch
git checkout correct-branch

# Apply your changes
git stash pop
```

### Need to Undo Last Commit

```bash
# Undo commit but keep changes
git reset --soft HEAD~1

# Undo commit and discard changes
git reset --hard HEAD~1
```

### Need to Update Commit Message

```bash
# Most recent commit
git commit --amend -m "new message"

# Older commit (interactive rebase)
git rebase -i HEAD~3
# Change 'pick' to 'reword' for the commit
```

### Accidentally Committed to Main

```bash
# Create a branch with your commits
git branch my-feature

# Reset main to origin
git reset --hard origin/main

# Switch to your feature branch
git checkout my-feature
```

### Merge Conflicts

```bash
# During rebase or merge, if conflicts occur:

# 1. Open conflicted files and resolve
# Look for <<<<<<< ======= >>>>>>> markers

# 2. Stage resolved files
git add resolved-file.ts

# 3. Continue the rebase/merge
git rebase --continue
# or
git merge --continue
```

## Branch Protection

The `main` branch has these protections:

- Requires pull request
- Requires passing CI checks
- Requires up-to-date branch
- No force pushes allowed

## Tips

### Useful Aliases

Add to your `~/.gitconfig`:

```ini
[alias]
    st = status
    co = checkout
    br = branch
    ci = commit
    lg = log --oneline --graph --all
    unstage = reset HEAD --
    last = log -1 HEAD
    branches = branch -a
```

### Before Every PR

1. Run tests: `npm run test:editor`
2. Run type check: `npx tsc --noEmit`
3. Run linter: `npx eslint packages/ --fix`
4. Review your diff: `git diff main`
5. Check commit history: `git log --oneline main..HEAD`

### Good Commit Hygiene

- Commit early and often
- Each commit should be atomic (one logical change)
- Commits should compile and pass tests
- Write meaningful commit messages
- Don't commit generated files
- Don't commit debug code