Branching strategy

We use trunk-based development with short-lived branches. The main branch is always releasable. Long-lived branches create merge pain, so we avoid them.

Branch types

Branch Naming Lifetime
Main main Permanent, protected
Feature feature/<ticket>-short-description 3 days or less
Fix fix/<ticket>-short-description 1 day or less
Release release/<yyyy.mm.dd> Until the release ships
Hotfix hotfix/<ticket> Hours

Ticket IDs follow the project's tracker, for example feature/PORT-142-login-form for a story on the Acme customer portal.

Everyday workflow

git checkout main
git pull
git checkout -b feature/PORT-142-login-form
# work, commit often
git push -u origin feature/PORT-142-login-form
# open a pull request, see Code review
  1. Branch from the latest main.
  2. Commit small, logical changes.
  3. Rebase on main at least daily to avoid drift.
  4. Open a pull request, see Code review.
  5. Squash merge once approved. Delete the branch after merging.

Commit messages

Use the imperative mood and reference the ticket:

PORT-142 Add validation to login form

Reject passwords shorter than 14 characters to match POL-IT-003.

Protected branch rules

  • Direct pushes to main are blocked.
  • A green build and an approval are required to merge.
  • Force-push is disabled on main and release branches.

Feature flags

For work that cannot be completed in three days, hide unfinished functionality behind a feature flag and merge it in small pieces. This lets the team release regularly, see Release process.

Hotfixes

A hotfix branches from the tag of the live release, is tested, and is merged to both the release branch and main. Hotfixes still need review, but the first review may be done in under an hour for P1 incidents; see Report an incident.

Repositories and access

Repositories are created by IT on request, and access is granted per Request access. Never store credentials in a repository.

Owner: Daniel Okafor - Last updated: 2026-01-29