Git Workflow & Branch Strategy

Standard ID: GIT-WORKFLOW Version: 1.0 Effective: 2026-04-03 Owner: CDO

1. Platform

Simpaisa uses Bitbucket for all source control. All repositories, pull requests, and CI pipelines operate within Bitbucket.

2. Branching Strategy

Trunk-based development with short-lived feature branches merging to main.

Branch Naming

Type	Pattern	Example
Feature	feature/{beads-id}-brief-description	feature/Architecture-abc-add-webhook-signing
Bug fix	fix/{beads-id}-brief-description	fix/Payments-x4f-null-callback-url
Release	release/v{major}.{minor}.{patch}	release/v2.3.0

• Use lowercase, hyphen-separated descriptions.
• Always include the Beads issue ID.
• Branch names must not exceed 80 characters.

Protected Branches

Branch	Protection
main	Require PR with at least 1 approval. No direct push. CI must pass.
release/*	Require PR with CDO approval.

3. Commit Messages

Use Conventional Commits format. Include the Beads issue ID in parentheses.

<type>: <description> (<beads-id>)

Types: feat, fix, docs, refactor, test, chore, perf, ci

Examples:

feat: add webhook HMAC signing (Architecture-o0u)
fix: correct idempotency key collision on retry (Payments-3kf)
docs: update pay-in sequence diagram (Architecture-abc)
refactor: extract RSA signing to shared module (Core-12d)

Rules: - Subject line: imperative mood, no capitalisation after type, no trailing full stop. - Body (optional): explain why, not what. Wrap at 72 characters. - Footer: reference related Beads issues with Refs: <id> or Closes: <id>.

4. Pull Request Process

1. Create PR in Bitbucket targeting main.
2. AI review first — run claude-code review on the branch before requesting human review.
3. Minimum 1 human reviewer must approve.
4. CI must pass — all tests, linting, and security scans green.
5. No unresolved comments — all PR comments must be resolved.
6. Squash merge to main — keeps history clean.

PR Title Format

<type>: <description> (<beads-id>)

Same convention as commit messages.

PR Description

Include: - Summary of changes (2-3 sentences). - Link to Beads issue. - Testing performed. - Rollback plan (if applicable).

5. Branch Lifecycle

• Feature branches must not live longer than 3 working days.
• If a branch exceeds 3 days, break the work into smaller increments.
• Delete branches immediately after merge (Bitbucket auto-delete enabled).
• Stale branches (>5 days, no activity) are subject to deletion without notice.

6. Merge Rules

• Squash merge to main — one commit per feature/fix.
• No rebase on shared branches — never rebase a branch that others have pulled.
• No force push to main or release/* under any circumstances.
• Resolve merge conflicts locally, test, then push.

7. CI Triggers

Event	Action
Push to feature/fix branch	Run unit tests, lint, security scan
PR created/updated	Run full test suite, build, integration tests
Merge to main	Run full suite + deploy to Dev
Tag v*	Build release artefact, deploy to Test

8. Release Process

1. Create release/v{version} branch from main.
2. Run full regression suite on the release branch.
3. CDO approves the release PR.
4. Merge to main, tag with v{version}.
5. Deploy tagged artefact through the promotion pipeline.

9. Hotfix Process

1. Branch fix/{beads-id}-description from main.
2. Apply fix, write/update tests.
3. PR with expedited review (CDO can be sole reviewer for P1 incidents).
4. Squash merge to main, tag if releasing immediately.

10. Compliance

• All commits must be attributable to an authenticated Bitbucket user.
• AI-generated commits must include Co-Authored-By trailer.
• Commit history is immutable once merged to main — no history rewriting.