Branching & Pull Requests

Branch strategy, PR lifecycle, reviews, and environment deployments.

This is the day-to-day workflow every developer follows. It connects Git branches to our Alpha → Beta → Prod environments.

Branch strategy

We use trunk-based development with short-lived feature branches:

Branch	Purpose	Lifetime	Deploys to
`main`	Integration branch — always deployable	Permanent	Beta (on merge)
`feature/*`	New work in progress	1–3 days max	Alpha (via PR)
`fix/*`	Bug fixes	1–2 days max	Alpha (via PR)
`hotfix/*`	Emergency production fixes	Hours	Alpha → fast-track to Prod

The PR lifecycle

Step-by-step: developer workflow

From idea to Beta

Create a branch from latest main: git checkout -b feature/short-description
Push commits and open a draft PR immediately — this triggers the Alpha preview.
Share the Alpha preview URL with your reviewer (posted as a PR comment by CI).
When ready, mark PR as "Ready for review" and assign a code owner.
Address feedback, push fixes — Alpha redeploys automatically on each push.
After approval, squash-merge to main — Beta deploys automatically.

Branch naming

plaintext

feature/add-user-dashboard     # New capability
fix/token-refresh-race         # Bug fix
hotfix/payment-gateway-error   # Production emergency
chore/upgrade-dependencies     # Tooling / maintenance
docs/update-git-workflow       # Documentation only

Format: {type}/{short-kebab-description} — lowercase, hyphens, no spaces.

Pull request template

Every PR must include:

markdown

## What changed
 
Brief description of the change and why.
 
## How to test
 
1. Open Alpha preview URL: {link}
2. Steps to verify the change
3. Expected result
 
## Environment impact
 
- [ ] Alpha preview tested
- [ ] No breaking API changes
- [ ] Env vars documented (if new)
 
## Screenshots / evidence
 
{attach screenshots or logs}

Review checklist

Before approving, reviewers confirm:

Alpha preview works as described
Code follows team conventions
Tests cover the change
No secrets or credentials in the diff
Database migrations are safe (if applicable)
Breaking changes are flagged and documented

Review SLAs

Role	Responsibility	Target
Author	Clear description, respond to feedback	Within 1 business day
Reviewer	Code quality, logic, security	Within 2 business days
Code owner	Domain approval, merge authority	Within 2 business days

What happens after merge

Merging to main does not deploy to Production. Production requires a separate release approval — see Release Process.

Commit messages

Follow Commit Conventions on every commit:

plaintext

feat(dashboard): add role-based access control
fix(auth): resolve token refresh race condition

These messages appear in the changelog when the change reaches Production.