OpenNoodl/dev-docs/guidelines/GIT-WORKFLOW.md

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

# 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

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

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

# 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

# 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

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

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

# 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

# Stash your changes
git stash

# Switch to correct branch
git checkout correct-branch

# Apply your changes
git stash pop

Need to Undo Last Commit

# 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

# 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

# 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

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

[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