Working with Git

Consistent Git practices make work easy to review, trace, and ship.

• Branch naming conventions
• Commits
• Rebasing feature branches
  • Linear history and why it matters
  • Safe rebase flow
• Merge requests

Branch naming conventions

Use descriptive, issue-linked branches so intent is clear at a glance.

Pattern	Purpose	Example
main	Default branch	main
feat/ISSUE-ID-short-description	New feature work	feat/ABC-123-dashboard-filters
fix/ISSUE-ID-short-description	Bug fixes	fix/ABC-456-null-guard
hotfix/ISSUE-ID-short-description	Urgent production fix	hotfix/ABC-789-login-outage
release/vX.Y.Z	Release branch	release/v1.2.0
chore/ISSUE-ID-short-description	Maintenance work	chore/ABC-321-deps-refresh

Why this matters

Clear branch names communicate intent and keep issues traceable during review and release work.

Commits

• Keep commits single responsibility.
• Use Conventional Commits (cheatsheet).
• Keep messages focused on intent and impact.

feat(api): add pagination to project list
fix(ui): prevent null avatar crash
chore(deps): bump vitepress to latest

Why this matters

Small, focused commits make the history easier to scan, revert, and audit.

Rebasing feature branches

Rebase your feature branch on top of the latest main to keep integration predictable and merge requests easier to review.

• Rebase regularly while developing, not only at the end.
• Keep your branch current with main and surface incompatibilities early.
• Resolve conflicts in smaller batches instead of one large merge conflict at handoff.
• Reduce merge noise so reviewers can focus on the actual feature work.

Why this matters

Frequent rebasing lowers integration risk, shortens review cycles, and avoids last-minute merge surprises.

Linear history and why it matters

Rebasing reapplies your commits on top of the latest main, which creates a clean, linear commit history.

• Linear history is easier to scan in git log and release timelines.
• Reviewers can follow intent without extra merge commits in the middle of feature work.
• Debugging and recovery workflows like git bisect, cherry-pick, and revert stay simpler.

Safe rebase flow

# update remote refs
git fetch origin

# rebase current branch onto latest main
git rebase origin/main

# if conflicts happen, resolve them and continue
git add <resolved-files>
git rebase --continue

# if needed, cancel and return to pre-rebase state
git rebase --abort

After a successful rebase, run tests and push your branch:

# rebasing rewrites commit hashes, so non-fast-forward push is expected
git push --force-with-lease

Why this requires force push

Rebasing creates new commits with new hashes. Your remote branch still points to the old commit chain, so a regular push is rejected. Use --force-with-lease instead of --force because it refuses to overwrite remote commits you have not fetched, which protects teammates' work.

Coordination rule

Avoid rebasing branches shared by multiple developers unless everyone working on that branch agrees first.

If a feature branch is shared, keep it current with main by merging main into the feature branch instead:

git fetch origin
git merge origin/main

This preserves commit hashes and usually avoids force pushes on a shared branch.

Merge requests

• Use project-provided templates whenever available.
• Title format: ISSUE-ID: Short Description of the Task.
• Own splitting your ticket into reviewable pieces.
• Keep merge requests small and easy to review.
• Create the MR as soon as development starts; set it to draft and assign a reviewer.
• Maintain a checklist in the MR description and check items as you build.
• Undraft only when work is complete and the project runs with tests passing.
• Keep descriptions clear and descriptive.
• Disclose the magnitude of AI usage (see AI Usage).
• Aim to close issues started that day before the day ends.

Why keep merge requests small

Large MRs are easy to skim past, and it is harder to keep a reliable mental map of changes.

Why start MRs early

Draft MRs promote transparency and give POs and reviewers time to plan their review schedule.

Why close issues daily

Closing issues daily builds planning discipline, supports smaller MRs, and encourages early communication when work takes longer.

Why this matters

Small, early, and transparent MRs reduce review fatigue, help the team plan, and keep the main branch moving.

Example MR checklist

• Add state field to ContractDTO
• Implement a procedure for contract.state inference
• Update tests
• Documentation updated
• Project runs locally
• Tests pass locally