Git Workflow

SALLY uses a trunk-based workflow with short-lived feature branches. All production code lives on main.

Branches

Main Branch

The main branch is the single source of truth. It should always be in a deployable state. You never commit directly to main — all changes go through pull requests.

Feature Branches

Create a branch from main for every change. Use this naming convention:

Keep branch names lowercase, hyphen-separated, and descriptive.

Workflow

1. Start from latest main

git checkout main
git pull origin main

2. Create your branch

git checkout -b feature/your-feature-name

3. Make commits

Commit early and often. Each commit should represent one logical change. See the commit conventions below.

4. Push and open a pull request

git push -u origin feature/your-feature-name

Then open a pull request on GitHub. See the Pull Request Guide for the expected format.

5. Address review feedback

Push additional commits to your branch as needed. Do not force-push unless the reviewer specifically requests you to rebase.

6. Merge

Once approved, merge to main using squash merge. Squash merging keeps the main history clean by collapsing your branch into a single commit.

7. Clean up

Delete your feature branch after it is merged:

git branch -d feature/your-feature-name

Commit Conventions

Format

type: short description

Keep the subject line under 72 characters. Use imperative mood (“add”, “fix”, “update” — not “added”, “fixed”, “updated”).

Types

Examples

feat: add driver deactivation endpoint
fix: resolve HOS calculation overflow for multi-day routes
refactor: extract monitoring trigger evaluation into service
docs: update API authentication guide
test: add integration tests for alert acknowledgment
chore: upgrade Prisma to 7.x
style: fix inconsistent indentation in route module

Multi-line Messages

For commits that need more context, add a blank line after the subject and write a body:

fix: resolve HOS calculation overflow for multi-day routes

The segment-by-segment HOS simulation was not resetting the driving
window counter after a full 10-hour rest. This caused the planner to
insert unnecessary rest stops on routes spanning 3+ days.

Added a window reset check in the HOS state machine and covered the
scenario with two new test cases.

Tips

• Keep branches short-lived. Aim to merge within 1-3 days. Long-running branches lead to painful merge conflicts.
• Pull main into your branch regularly if your branch lives longer than a day: git pull origin main (or rebase if you prefer).
• One logical change per commit. If you find yourself writing “and” in the commit message, consider splitting the commit.
• Do not mix refactoring with feature work in the same commit. Separate them so reviewers can evaluate each change on its own.