Skip to content

Git workflow

Jump to bottom
Juan Cobo Betancourt edited this page Jul 11, 2026 · 6 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
    • wiki/ → this developer wiki

⚠️ 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.

Branch protection & review policy

dev and main are protected on all three repos — no direct pushes, force-pushes, or branch deletions. Everything reaches these branches through a pull request; nothing is committed to them directly. The review bar differs by target:

  • Into dev: anyone may open a PR from their feature branch and merge it themselves — no second approval required. The rule is only that work arrives via a branch and a PR, never a direct commit.
  • From dev into main: requires at least one approving review and proper testing on dev first — including on target hardware (a Raspberry Pi) for anything that could affect runtime behaviour. A change with no functional impact — a licence update, a UI string or name change — still goes through review but does not need hardware testing. main is release-only, so it gets the fuller scrutiny.

The path a change takes:

  1. Branch from dev (<area>/<short-description>), open a PR into dev, and merge it once ready.
  2. Changes are integrated and tested on dev.
  3. When dev is proven, open a PR from dev into main, merge after review, and tag the release on main.

Admin bypass is off (enforce_admins), so it exists only as a safety valve for genuine solo unblocking, not for routine merges.

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   # take the exact pins the super-repo records (no --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 -C frontend fetch origin                 # or backend
git -C frontend checkout <merged-sha>        # the exact commit merged in the submodule PR
                                             # (read it with: git -C frontend rev-parse --short HEAD)
git add frontend
git commit -m "chore(submodule): bump frontend to <short-sha>"
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