Git Conventions

Branching Strategy & Commit Guidelines

Home | SoftLixx Creates

Git Conventions Overview

Standardized version control practices

This document establishes Git branching strategies, naming conventions, and commit message standards for the AlKareem ERP project. Consistent Git practices ensure clean history, easier collaboration, and streamlined code reviews.

Branch Strategy

Feature branches from dev, merged via PR with review.

Naming Standards

Descriptive branch names with type prefixes.

Commit Messages

Conventional Commits format with type and scope.

Branching Strategy

Git Flow adapted for ERP development

Main Branch

main

  • Production-ready code only
  • Protected branch, requires PR approval
  • Tagged with version numbers (v1.0.0)
  • Direct commits prohibited

Development Branch

dev

  • Integration branch for features
  • All feature branches merge here first
  • Deployed to staging for QA testing
  • Merged to main after sprint completion

Feature Branches

feature/module-name

  • Created from dev branch
  • One feature/module per branch
  • Merged back to dev via Pull Request
  • Deleted after successful merge

Hotfix Branches

hotfix/issue-description

  • Created from main for urgent fixes
  • Merged to both main and dev
  • Requires immediate testing and approval
  • Version patch increment (v1.0.1)

Git Flow Visualization

gitGraph commit id: "Initial commit" branch dev checkout dev commit id: "Setup project" branch feature/accounting checkout feature/accounting commit id: "Add CoA" commit id: "Journal entries" checkout dev merge feature/accounting tag: "v0.1.0" branch feature/inventory checkout feature/inventory commit id: "Stock model" commit id: "Warehouse logic" checkout dev merge feature/inventory tag: "v0.2.0" checkout main merge dev tag: "v1.0.0" branch hotfix/stock-calc checkout hotfix/stock-calc commit id: "Fix stock bug" checkout main merge hotfix/stock-calc tag: "v1.0.1" checkout dev merge hotfix/stock-calc

Branch Naming Conventions

Structured and descriptive branch names

Pattern Format

<type>/<module>-<short-description>

All lowercase, use hyphens for spaces, keep descriptions concise (3-5 words max).

Feature Branches

feature/accounting-chart-of-accounts
feature/inventory-stock-transfer
feature/hr-attendance-tracking

Bugfix Branches

bugfix/purchase-order-validation
bugfix/payroll-calculation-error
bugfix/invoice-number-duplicate

Hotfix Branches

hotfix/critical-stock-negative
hotfix/payment-gateway-timeout
hotfix/auth-token-expiry

Refactor/Chore

refactor/accounting-service-layer
chore/update-dependencies
chore/setup-ci-pipeline

Commit Message Format

Conventional Commits specification

Standard Format

<type>(<scope>): <subject>
[optional body]
[optional footer]

Commit Types

feat
Feature

New feature or functionality

fix
Bug Fix

Fixes a bug or error

docs
Documentation

Documentation changes only

refactor
Refactor

Code restructuring without behavior change

test
Tests

Adding or updating tests

chore
Chore

Build process, dependencies, tooling

perf
Performance

Performance improvements

style
Style

Formatting, whitespace, linting

Commit Message Examples

✅ Good Examples:

feat(accounting): add chart of accounts CRUD operations
fix(inventory): correct stock calculation in transfer process
docs(readme): update installation instructions for PHP 8.2
refactor(purchase): extract GRN logic to dedicated service class

❌ Bad Examples:

updated files
bug fix
WIP accounting module

Development Workflow

Step-by-step Git workflow

1

Create Feature Branch

git checkout dev
git pull origin dev
git checkout -b feature/accounting-ledger-accounts
2

Develop and Commit Changes

# Make changes to code
git add .
git commit -m "feat(accounting): add ledger account model and repository"

Commit frequently with meaningful messages. Keep commits atomic.

3

Push to Remote

git push -u origin feature/accounting-ledger-accounts
4

Create Pull Request

  • Base: dev | Compare: feature/accounting-ledger-accounts
  • Add clear title and description
  • Link related issues/tickets
  • Request reviewers
5

Code Review and Merge

  • Address review comments and push updates
  • Ensure all CI/CD checks pass
  • Get approval from at least one reviewer
  • Squash and merge to dev
6

Cleanup

git checkout dev
git pull origin dev
git branch -d feature/accounting-ledger-accounts

Best Practices

Tips for effective version control

Do's

  • Pull latest changes before creating a new branch
  • Commit frequently with atomic, logical changes
  • Write descriptive PR descriptions with screenshots if UI changed
  • Rebase feature branches to keep history clean
  • Run tests locally before pushing
  • Delete branches after merging

Don'ts

  • Never commit directly to main or dev branches
  • Avoid large monolithic commits with multiple unrelated changes
  • Don't use vague commit messages like "fix", "update", "WIP"
  • Avoid force-pushing to shared branches
  • Don't commit sensitive data (credentials, API keys)
  • Don't merge without code review approval