Skip to content

Git workflow

Jump to bottom
jairomelo edited this page Jan 3, 2026 · 3 revisions

This guide explains how we work with Git, branches, pull requests, and Docker to ensure smooth collaboration across the super-repo and its submodules.

Repository Structure

  • Super-repo (this repository): Holds orchestration (docker-compose.yml), environment examples, documentation, and submodule pointers.

  • Submodules:

    • frontend/ → SvelteKit application
    • backend/ → FastAPI application

⚠️ Most day-to-day coding happens inside the submodule repos. The super-repo is responsible for keeping everything in sync.

Branching Model

We follow a Gitflow-style workflow:

Main Branches

  • main → production-ready code only (tagged releases).
  • dev → integration branch for reviewed contributions.

Feature Branches

  • Always branch from dev.

  • Use the format:

    <area>/<short-description>

    Examples:

    • ui/capture-panel
    • api/upload-endpoint
    • ops/docker-compose-prod

Hotfix Branches

  • For urgent fixes from main:

    hotfix/<issue>

    Merge back into main and then forward into dev.

Workflow for Submodules

1. Prepare checkout

git fetch --all
git switch dev # or main for hotfixes
git pull origin dev # ensure up to date
git submodule update --init --recursive --remote

2. Create a feature branch in a submodule

cd frontend
git checkout dev
git pull origin dev
git checkout -b ui/capture-panel

Do your work, commit often, then push:

git push -u origin ui/capture-panel

3. Open a PR in the submodule repo

  • Target branch: dev
  • Request at least 1 reviewer

4. Update the super-repo pointer

After merging in the submodule:

cd ..
git checkout dev
git pull origin dev
git submodule update --remote frontend   # or backend
git add frontend
git commit -m "chore(submodule): bump frontend to <sha> for ui/capture-panel"
git push

Open a PR in the super-repo (target: dev).

Commit Guidelines

  • Write atomic, descriptive commits:

    • feat(api): add /upload endpoint
    • fix(ui): handle 404 from /health
    • chore(docs): add onboarding guide

Pull Request Checklist

  • Code builds & runs in Docker (docker compose up --build)
  • Tests pass (if available)
  • Commit messages are meaningful
  • No unresolved merge conflicts
  • Documentation updated if needed
  • Reviewers assigned

Working with Docker

All development happens inside Docker. You do not need to install Node.js or Python locally.

Switching branches safely:

  • If only source files changed: just git checkout <branch>

  • If dependencies changed (package*.json or requirements.txt):

    docker compose down -v
docker compose up --build

Release Flow

  • Submodules: merge dev → main, tag (e.g., v0.2.0), CI builds Docker images.
  • Super-repo: update submodule pointers, merge dev → main, tag release.
  • Deliverables published openly (per Data Management Plan).

Weekly Cadence

  • Mon–Thu: work in feature branches
  • Fri: review PRs → merge into dev (submodules first, then super-repo)
  • Milestone complete: merge dev → main, tag, release notes

Clone this wiki locally