Development Workflow

This guide describes the day-to-day Git workflow for contributing to FUSION.

Branch Strategy

FUSION uses a three-tier branch strategy:

Main Branches

main: Fully stable, production-ready code
release/*: Stabilization branches (e.g., release/v6.1) - more stable but working out kinks
develop: Integration branch for fresh/unstable features (internal team only)

Working Branches

feature/*: New features (e.g., feature/add-new-algorithm)
fix/*: Bug fixes (e.g., fix/routing-error)
docs/*: Documentation changes (e.g., docs/update-readme)
refactor/*: Code refactoring (e.g., refactor/cli-structure)

For External Contributors

If you’re contributing from outside the core team, work from the stable main branch:

# Update main branch first
git checkout main
git pull upstream main

# Create and switch to a new branch
git checkout -b feature/my-new-feature

Your pull requests should target main. The team will handle integration.

For Internal Team

Core team members work from the develop branch:

# Update develop branch first
git checkout develop
git pull upstream develop

# Create and switch to a new branch
git checkout -b feature/my-new-feature

Internal Branch Flow

feature/* ─┐
fix/*     ─┼──> develop ──> release/* ──> main
docs/*    ─┘

Create working branches from develop
Merge completed work into develop
When ready for release, develop merges into a release/* branch
After stabilization, release/* merges into main

Use descriptive branch names that indicate what you’re working on.

Making Changes

Make your changes to the code
Check what changed
```
git status
git diff
```

Stage your changes

# Stage specific files
git add path/to/file.py

# Or stage all changes
git add .

Commit with a descriptive message
```
git commit -m "feat(routing): add congestion-aware path selection"
```
See Commit Messages for commit message guidelines.
Push to your fork
```
git push origin feature/my-new-feature
```

Running Quality Checks

Before pushing, run the quality checks:

# Format code
make format

# Run linting
make lint

# Run tests
make test

# Run all checks
make check-all

Pre-commit hooks will also run automatically when you commit.

Keeping Your Branch Updated

If the base branch has been updated while you’re working:

# Fetch upstream changes
git fetch upstream

# Rebase your branch (use main for external, develop for internal)
git rebase upstream/main   # External contributors
# OR
git rebase upstream/develop   # Internal team

# If there are conflicts, resolve them, then:
git rebase --continue

# Force push to update your branch (only for your own branches)
git push origin feature/my-new-feature --force-with-lease

Common Git Commands

# Check current status
git status

# View commit history
git log --oneline

# Undo staged changes
git restore --staged <file>

# Discard local changes
git restore <file>

# Stash changes temporarily
git stash
git stash pop

# Switch branches
git checkout branch-name

# Delete a local branch
git branch -d branch-name