Skip to content

Git Workflow

This guide documents the Git workflow and conventions used in CalcBridge development. Following these practices ensures a clean commit history, easy code reviews, and reliable releases.

Branch Strategy

CalcBridge uses a trunk-based development approach with feature branches:

gitGraph
    commit id: "main"
    branch feature/CB-123-add-xlookup
    commit id: "Implement parser"
    commit id: "Add tests"
    checkout main
    branch bugfix/CB-456-fix-auth
    commit id: "Fix token validation"
    checkout main
    merge bugfix/CB-456-fix-auth
    checkout feature/CB-123-add-xlookup
    commit id: "Address review"
    checkout main
    merge feature/CB-123-add-xlookup
    commit id: "Release v1.1.0" type: HIGHLIGHT

Branch Types

Prefix Purpose Example
feature/ New features feature/CB-123-add-xlookup-function
bugfix/ Bug fixes bugfix/CB-456-fix-token-refresh
hotfix/ Critical production fixes hotfix/CB-789-security-patch
docs/ Documentation changes docs/CB-101-update-api-docs
refactor/ Code refactoring refactor/CB-202-cleanup-parser
test/ Test improvements test/CB-303-add-integration-tests

Branch Naming Convention

<type>/<ticket-id>-<short-description>

Rules:

  • Use lowercase with hyphens
  • Include the ticket/issue ID
  • Keep descriptions concise (2-5 words)
  • Use present tense verbs

Examples:

# Good
feature/CB-123-add-xlookup-function
bugfix/CB-456-fix-null-handling
hotfix/CB-789-patch-auth-bypass

# Avoid
Feature/CB123_AddXlookup        # Wrong case, underscores
fix-auth-bug                     # Missing ticket ID
feature/CB-123                   # No description

Creating Branches

Start New Work

# Ensure main is up to date
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/CB-123-add-xlookup-function

# Make changes and commit
git add -A
git commit -m "Add XLOOKUP function to parser

Implements the XLOOKUP function with support for:
- Exact match
- Approximate match
- Error handling for missing values

Closes #123"

# Push branch
git push -u origin feature/CB-123-add-xlookup-function

Keep Branch Updated

# Regularly sync with main
git fetch origin
git rebase origin/main

# Or merge if you prefer
git merge origin/main

Commit Message Format

Follow the conventional commits specification for clear, parseable commit history.

Structure

<type>(<scope>): <subject>

<body>

<footer>

Types

Type Description
feat New feature
fix Bug fix
docs Documentation only
style Code formatting (no logic change)
refactor Code restructuring (no feature/fix)
perf Performance improvement
test Adding or updating tests
build Build system or dependencies
ci CI/CD configuration
chore Maintenance tasks

Scopes

Scope Area
api API routes and handlers
parser Formula parser
calc Calculation engine
db Database models/migrations
auth Authentication
worker Celery tasks
frontend Next.js frontend

Examples

# Feature
feat(parser): add XLOOKUP function support

Implements the XLOOKUP function with exact and approximate match modes.
Supports error handling for missing lookup values.

Closes #123

# Bug fix
fix(auth): prevent token refresh after logout

The refresh endpoint now checks if the token's JTI has been revoked
before issuing new tokens.

Fixes #456

# Documentation
docs(api): update authentication endpoint examples

# Performance
perf(calc): optimize vectorized SUMIF by 40%

Replace iterrows() with boolean masking for significant speedup
on large datasets (1M+ rows).

# Refactoring
refactor(db): extract base repository pattern

Move common CRUD operations to BaseRepository class.
No functional changes.

Commit Message Rules

  1. Subject line:
  2. Use imperative mood ("add" not "added" or "adds")
  3. Capitalize first letter
  4. No period at the end

  5. Max 72 characters

  6. Body (optional):

  7. Wrap at 72 characters
  8. Explain what and why, not how

  9. Separate from subject with blank line

  10. Footer (optional):

  11. Reference issues: Closes #123, Fixes #456
  12. Note breaking changes: BREAKING CHANGE: ...

Pull Request Process

Creating a Pull Request

  1. Push your branch: 

    git push origin feature/CB-123-add-xlookup-function

  2. Open PR on GitHub with this template:

## Summary

Brief description of changes (1-2 sentences).

## Changes

- Added XLOOKUP function to parser
- Implemented vectorized lookup with numpy
- Added comprehensive test coverage

## Testing

- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist

- [ ] Code follows style guide
- [ ] Tests pass locally
- [ ] Documentation updated
- [ ] No security vulnerabilities
- [ ] Reviewer assigned

## Related Issues

Closes #123

PR Title Convention

Follow the same format as commit messages:

feat(parser): add XLOOKUP function support
fix(auth): prevent token refresh after logout
docs: update deployment guide

PR Size Guidelines

Size Lines Changed Recommended
XS < 50 Quick review
S 50-200 Normal review
M 200-500 Detailed review
L 500-1000 Split if possible
XL > 1000 Must split

Keep PRs Small

Smaller PRs are reviewed faster and more thoroughly. If your PR is large, consider splitting it into logical chunks.

Code Review Guidelines

For Authors

  1. Self-review first: Check your own code before requesting review
  2. Provide context: Explain the why in PR description
  3. Respond promptly: Address feedback within 24 hours
  4. Be open to feedback: Reviewers are helping improve the code

For Reviewers

  1. Be constructive: Suggest improvements, don't just criticize
  2. Ask questions: If something is unclear, ask
  3. Prioritize: Focus on logic, security, and correctness first
  4. Approve when ready: Don't block on minor style issues

Review Checklist

## Review Checklist

### Functionality
- [ ] Code does what the PR claims
- [ ] Edge cases handled
- [ ] Error handling is appropriate

### Code Quality
- [ ] Code is readable and maintainable
- [ ] No unnecessary complexity
- [ ] DRY principle followed

### Testing
- [ ] Tests cover new functionality
- [ ] Tests cover edge cases
- [ ] Tests pass in CI

### Security
- [ ] No hardcoded secrets
- [ ] Input validation present
- [ ] SQL injection prevented
- [ ] Authentication/authorization correct

### Performance
- [ ] No N+1 queries
- [ ] Vectorized operations used
- [ ] No memory leaks

CI/CD Pipeline

Automated Checks

Every PR triggers these checks:

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: pip install ruff
      - name: Lint
        run: ruff check src/ tests/

  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: test
        ports:
          - 5432:5432
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: pip install -e ".[dev,test]"
      - name: Run tests
        run: |
          PYTHONPATH=. pytest tests/ \
            --cov=src \
            --cov-report=xml \
            --cov-fail-under=80

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run security scan
        run: |
          pip install bandit safety
          bandit -r src/
          safety check

Required Checks

PRs must pass these before merging:

Check Description
Lint Ruff check passes
Tests All tests pass
Coverage >= 80% coverage
Security No vulnerabilities
Build Docker image builds

Merging Strategy

Squash and Merge

Default strategy for feature branches:

  • Combines all commits into one
  • Creates clean linear history
  • Use descriptive merge commit message
feat(parser): add XLOOKUP function support (#123)

* Implement XLOOKUP parser node
* Add vectorized lookup function
* Add comprehensive tests
* Update documentation

Rebase and Merge

For clean branches with good commit history:

  • Preserves individual commits
  • Maintains linear history
  • Each commit should be atomic

Merge Commit

For release branches or when history must be preserved:

  • Creates merge commit
  • Preserves branch history
  • Use for release merges

Release Process

Version Numbering

Follow semantic versioning (SemVer):

MAJOR.MINOR.PATCH
  |     |     |
  |     |     +-- Bug fixes, no API changes
  |     +-------- New features, backward compatible
  +-------------- Breaking changes

Examples:

  • 1.0.0 -> 1.0.1: Bug fix
  • 1.0.1 -> 1.1.0: New feature
  • 1.1.0 -> 2.0.0: Breaking change

Creating a Release

# Ensure main is up to date
git checkout main
git pull origin main

# Create release tag
git tag -a v1.1.0 -m "Release v1.1.0

Features:
- Add XLOOKUP function support
- Improve calculation performance

Bug Fixes:
- Fix token refresh after logout
- Handle null values in SUMIF"

# Push tag
git push origin v1.1.0

Hotfix Process

For critical production fixes:

# Create hotfix branch from latest tag
git checkout v1.0.0
git checkout -b hotfix/CB-789-security-patch

# Make fix
git commit -m "fix(auth): patch authentication bypass

Addresses critical security vulnerability in token validation."

# Create PR to main
git push origin hotfix/CB-789-security-patch

# After merge, tag new release
git checkout main
git pull origin main
git tag -a v1.0.1 -m "Hotfix release v1.0.1"
git push origin v1.0.1

Common Git Commands

Daily Workflow

# Start new feature
git checkout main && git pull
git checkout -b feature/CB-123-description

# Stage and commit
git add -A
git commit -m "feat(scope): description"

# Push changes
git push -u origin feature/CB-123-description

# Update from main
git fetch origin
git rebase origin/main

# Resolve conflicts if needed
git rebase --continue  # After resolving
git rebase --abort     # To cancel

Useful Commands

# View branch history
git log --oneline --graph -20

# See changes in a commit
git show abc123

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Stash work in progress
git stash
git stash pop

# Clean up merged branches
git branch --merged | grep -v main | xargs git branch -d

# Interactive rebase (clean up commits)
git rebase -i HEAD~3

Best Practices Summary

  1. Branch early, branch often: Keep branches focused and short-lived
  2. Commit atomically: Each commit should be a logical unit
  3. Write good messages: Future you will thank present you
  4. Keep main green: Never commit broken code to main
  5. Review thoughtfully: Code review is a learning opportunity
  6. Test before pushing: Run tests locally before pushing
  7. Clean up after merge: Delete merged branches