Skip to content

Branch Rules & Conventions

This document defines the branching strategy, commit message format, pull request workflow, and merge policies for the Feoda BI repository hosted on Azure Repos.

Branch Strategy

main                    ← Production-ready code (protected)
├── develop             ← Integration branch for sprint work (protected)
│   ├── feature/BI-xx   ← Feature branches (linked to Azure Boards work item)
│   ├── bugfix/BI-xx    ← Bug fix branches
│   └── spike/BI-xx     ← Research/spike branches
├── release/v0.x        ← Release candidates
└── hotfix/BI-xx        ← Urgent production fixes

Branch Types

Prefix Purpose Base Branch Merges Into
feature/BI-xx-description New functionality develop develop
bugfix/BI-xx-description Bug fixes develop develop
spike/BI-xx-description Research / proof of concept develop develop (or discard)
release/v0.x Release candidate preparation develop main + develop
hotfix/BI-xx-description Urgent production fix main main + develop

Branch Naming Rules

  • Always prefix with the branch type: feature/, bugfix/, spike/, release/, hotfix/
  • Include the Azure Boards work item ID: BI-xx
  • Add a short kebab-case description: feature/BI-17-database-migrations
  • Keep it concise — the work item has the full details

Examples:

feature/BI-17-database-migrations
feature/BI-21-coding-standards
bugfix/BI-42-invoice-rounding-error
spike/BI-30-payment-gateway-options
hotfix/BI-99-critical-billing-fix
release/v0.1

Commit Message Convention

Use the AB#<id> prefix to auto-link commits to Azure Boards work items:

AB#<work-item-id> <short description>

Examples:

AB#17 Add initial tenant migration
AB#21 Configure ESLint and Prettier rules
AB#42 Fix invoice rounding for partial payments

Rules

  • The AB#<id> prefix is required — it links the commit to the work item's Development tab in Azure Boards
  • Use imperative mood ("Add", "Fix", "Update" — not "Added", "Fixes", "Updated")
  • Keep the first line under 72 characters
  • Add a blank line and body for complex changes:
AB#17 Add initial tenant migration

Creates the tenants table with columns for name, slug, timezone,
currency, and status. Includes unique constraint on slug and
index on status for active tenant queries.

Pull Request Workflow

Creating a PR

  1. Push your feature branch to Azure Repos
  2. Go to Repos → Pull Requests → New pull request
  3. Source: your feature branch → Target: develop (or main for releases/hotfixes)
  4. Fill in the PR template:
  5. Summary — what does this PR do?
  6. Related Work Items — use AB#<id> to link work items
  7. Changes — bullet list of what changed
  8. Testing — check off the quality gates
  9. Checklist — self-review, conventions, no warnings

PR Requirements (Branch Policies)

Both main and develop have branch policies enforced:

Policy Requirement
Minimum reviewers 1 reviewer must approve
Work item linking At least one work item must be linked
Comment resolution All PR comments must be resolved
Merge type Squash merge only
Build validation CI pipeline must pass (lint, type-check, tests)

PR Template

The repository includes a PR template at .azuredevops/pull_request_template.md that auto-populates when creating a PR. Fill in all sections.

Code Review Expectations

As a reviewer:

  • Review within 24 hours of being assigned
  • Focus on correctness, readability, and adherence to conventions
  • Leave actionable comments — suggest fixes, not just problems
  • Approve when satisfied; request changes if blocking issues exist

As an author:

  • Self-review your own PR before requesting review
  • Keep PRs small and focused — one feature or fix per PR
  • Respond to review comments promptly
  • Don't push new changes during active review without notifying the reviewer

Merge Policy

Squash Merge

All PRs use squash merge — the entire feature branch is compressed into a single commit on the target branch. This keeps the history on develop and main clean and linear.

The squash commit message should follow the commit message convention:

AB#17 Add database migrations setup

After Merge

  • The feature branch can be deleted after merge (Azure DevOps offers this automatically)
  • The CI pipeline runs on the merge commit
  • Work item automation moves linked items through the board:
  • PR created → work item moves to Pull Request column (Resolved state)
  • PR merged → work item moves to Done column (Closed state)

Protected Branches

main

  • Production-ready code only
  • Receives merges from develop (via release PRs) and hotfix/ branches
  • All branch policies enforced
  • No direct pushes allowed

develop

  • Integration branch for sprint work
  • Receives merges from feature/, bugfix/, and spike/ branches
  • All branch policies enforced
  • No direct pushes allowed

Workflow Summary

graph LR
    A[develop] -->|checkout| B[feature/BI-xx]
    B -->|commit + push| B
    B -->|PR| C[Code Review]
    C -->|approve| D[Squash Merge]
    D -->|auto| A
    A -->|release PR| E[main]
  1. Pull latest develop
  2. Create a feature branch: feature/BI-xx-description
  3. Commit with AB#<id> prefix
  4. Push and create a PR to develop
  5. CI pipeline runs automatically
  6. Reviewer approves
  7. Squash merge into develop
  8. Delete the feature branch