Version Control

Git Workflow and Branching Strategy

Version Control Overview

The Shirinzad E-Commerce Platform follows industry-standard Git workflows with conventional commit messages and a structured branching strategy to ensure code quality and streamlined collaboration.

Key Principles: Atomic commits, meaningful commit messages, code review before merging, and protected production branches.

Version Control Goals

  • Maintain clean and readable commit history
  • Enable parallel development of features
  • Facilitate code review and collaboration
  • Support rapid hotfix deployment
  • Ensure production stability
  • Enable easy rollback when needed

Git Branching Strategy

The project follows a modified Git Flow branching model optimized for continuous delivery.

gitGraph commit id: "Initial commit" branch develop checkout develop commit id: "Setup project" branch feature/products checkout feature/products commit id: "Add product entity" commit id: "Add product service" checkout develop merge feature/products branch feature/orders checkout feature/orders commit id: "Add order entity" commit id: "Add checkout flow" checkout develop merge feature/orders checkout main merge develop tag: "v1.0.0" checkout develop branch feature/payments checkout feature/payments commit id: "Add payment gateway" checkout main branch hotfix/security-fix commit id: "Fix security issue" checkout main merge hotfix/security-fix tag: "v1.0.1" checkout develop merge hotfix/security-fix merge feature/payments checkout main merge develop tag: "v2.0.0"

Git Flow branching model with feature branches, hotfixes, and releases

Branch Types and Conventions

1. Master Branch (Main)

The production-ready branch containing stable, released code.

Purpose Production deployments
Protection Highly protected, requires PR approval
Merge Source develop (releases), hotfix/* branches
Tagging All merges are tagged with version (v1.0.0, v2.0.0)
Direct Commits Prohibited
Rule: Never commit directly to master. All changes must go through pull requests.

2. Develop Branch

The integration branch for features, containing the latest development changes.

Purpose Integration of features, staging deployments
Protection Protected, requires PR and passing tests
Merge Source feature/*, bugfix/*, hotfix/* branches
Deployment Automatically deployed to staging
Direct Commits Allowed for minor fixes (discouraged)

3. Feature Branches

Short-lived branches for developing new features.

Naming Convention

feature/<feature-name>
feature/<ticket-number>-<feature-name>

Examples:
feature/product-reviews
feature/payment-gateway
feature/123-shopping-cart
feature/456-user-wishlist
Created From develop
Merged Into develop
Lifespan Days to weeks
Deletion Delete after merge

Workflow

# Create feature branch
git checkout develop
git pull origin develop
git checkout -b feature/product-reviews

# Work on feature
git add .
git commit -m "feat(products): add review submission endpoint"

# Keep branch updated with develop
git checkout develop
git pull origin develop
git checkout feature/product-reviews
git rebase develop

# Push and create PR
git push -u origin feature/product-reviews
# Create pull request on GitHub

4. Hotfix Branches

Emergency fixes for production issues.

Naming Convention

hotfix/<issue-description>
hotfix/<version>

Examples:
hotfix/payment-validation
hotfix/security-vulnerability
hotfix/1.0.1
Created From master
Merged Into master AND develop
Lifespan Hours to 1-2 days
Priority High - immediate deployment

Workflow

# Create hotfix branch
git checkout master
git pull origin master
git checkout -b hotfix/payment-validation

# Fix the issue
git add .
git commit -m "fix(payment): add null check for payment method"

# Merge to master
git checkout master
git merge --no-ff hotfix/payment-validation
git tag -a v1.0.1 -m "Hotfix: Payment validation"
git push origin master --tags

# Merge to develop
git checkout develop
git merge --no-ff hotfix/payment-validation
git push origin develop

# Delete hotfix branch
git branch -d hotfix/payment-validation

5. Release Branches

Preparation branches for production releases (optional).

Naming Convention

release/<version>

Examples:
release/1.0.0
release/2.0.0
Created From develop
Merged Into master AND develop
Purpose Final testing, version bumps, changelog
Commits Bug fixes, documentation, version updates only

6. Bugfix Branches

Non-critical bug fixes for the develop branch.

Naming Convention

bugfix/<issue-description>

Examples:
bugfix/cart-calculation-error
bugfix/image-upload-validation
Created From develop
Merged Into develop
Usage Fix bugs found during development/testing

Commit Message Conventions

The project follows the Conventional Commits specification for clear and structured commit messages.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Commit Types

Type Description Example
feat New feature feat(products): add product review system
fix Bug fix fix(cart): correct quantity calculation
docs Documentation changes docs(api): update API documentation
style Code style/formatting style: apply prettier formatting
refactor Code refactoring refactor(orders): simplify order creation logic
perf Performance improvement perf(products): add index for product search
test Add/update tests test(orders): add order cancellation tests
build Build system changes build: update NuGet packages
ci CI/CD changes ci: add automated deployment to staging
chore Other changes chore: update gitignore
security Security fixes security: fix SQL injection vulnerability

Common Scopes

Modules

  • products
  • orders
  • cart
  • payments
  • users
  • auth

Layers

  • domain
  • application
  • infrastructure
  • api
  • web

Cross-Cutting

  • cache
  • logging
  • security
  • config
  • db

Commit Message Examples

Simple Commit

feat(products): add product image gallery

Allow multiple images per product with ordering support.

Bug Fix

fix(cart): prevent negative quantities

Add validation to ensure cart item quantity is always positive.

Breaking Change

feat(api)!: change product API response format

BREAKING CHANGE: Product API now returns nested category object instead of categoryId.

Before:
{
  "id": "...",
  "categoryId": "123"
}

After:
{
  "id": "...",
  "category": {
    "id": "123",
    "name": "Electronics"
  }
}

Multiple Changes

feat(orders): implement order cancellation workflow

- Add CancelOrderAsync method to OrderAppService
- Add order status validation before cancellation
- Add unit tests for cancellation scenarios
- Update API documentation

Closes #234
Related #235

Performance Improvement

perf(products): optimize product search query

- Add composite index on (IsActive, CategoryId, Price)
- Use AsNoTracking for read-only queries
- Implement query result caching

Query time reduced from 450ms to 80ms on 10,000 products.

Security Fix

security(auth): fix JWT token validation

Ensure token expiration is properly validated.
Add additional claims validation.

CVE: None (internal finding)
Severity: High

Pull Request Workflow

sequenceDiagram participant Dev as Developer participant Branch as Feature Branch participant CI as CI Pipeline participant Reviewer as Code Reviewer participant Develop as Develop Branch Dev->>Branch: Create feature branch Dev->>Branch: Commit changes Dev->>Branch: Push to remote Dev->>CI: Create Pull Request CI->>CI: Run build CI->>CI: Run tests CI->>CI: Check code coverage CI->>CI: Run linting alt CI Fails CI-->>Dev: Notify failure Dev->>Branch: Fix issues Dev->>CI: Push fixes end CI-->>Reviewer: All checks passed Reviewer->>Reviewer: Review code alt Changes Requested Reviewer-->>Dev: Request changes Dev->>Branch: Make changes Dev->>CI: Push updates CI->>CI: Re-run checks end Reviewer->>Develop: Approve PR Dev->>Develop: Merge PR Develop->>Branch: Delete branch

Pull Request Guidelines

Creating a Pull Request

PR Title Format

Same as commit message format:
<type>(<scope>): <description>

Examples:
feat(products): Add product review system
fix(cart): Correct discount calculation
perf(orders): Optimize order query performance

PR Description Template

## Summary
Brief description of the changes and why they were made.

## Changes
- List of specific changes
- Another change
- One more change

## Testing
- How to test these changes
- Test scenarios covered
- Edge cases considered

## Screenshots (if applicable)
[Add screenshots for UI changes]

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All tests passing
- [ ] No new warnings introduced

## Related Issues
Closes #123
Related #456

Code Review Guidelines

For Authors

  • Keep PRs small and focused (under 400 lines)
  • Provide clear description and context
  • Ensure all CI checks pass before requesting review
  • Respond promptly to review comments
  • Test your changes thoroughly
  • Update documentation as needed

For Reviewers

  • Review within 24 hours
  • Check code quality, not just functionality
  • Look for potential bugs and edge cases
  • Verify tests cover the changes
  • Provide constructive feedback
  • Approve only when all concerns are addressed

Review Checklist

Category What to Check
Functionality Does the code do what it's supposed to do?
Code Quality Is the code clean, readable, and maintainable?
Tests Are there adequate tests? Do they pass?
Performance Any performance concerns? N+1 queries?
Security Any security vulnerabilities?
Error Handling Are errors handled appropriately?
Documentation Are docs updated? Complex code commented?

Merge Strategies

Merge Commit

Creates a merge commit preserving branch history.

git merge --no-ff feature/branch

Use For

  • Feature branches to develop
  • Hotfix branches to master
  • Release branches

Pros

  • Preserves complete history
  • Easy to revert entire feature
  • Clear feature boundaries

Squash and Merge

Combines all commits into a single commit.

git merge --squash feature/branch
git commit -m "feat: add feature"

Use For

  • Small feature branches
  • Bug fixes
  • Clean linear history

Pros

  • Clean, linear history
  • One commit per feature
  • Easy to read git log

Rebase and Merge

Replays commits on top of target branch.

git rebase develop
git checkout develop
git merge feature/branch

Use For

  • Keeping feature branch updated
  • Linear history preference

Pros

  • Linear history
  • No merge commits
  • Clean git log

Recommended Strategy by Branch Type

Source Target Strategy Reason
feature/* develop Squash or Merge Commit Clean history, one logical change
develop master Merge Commit Preserve release history
hotfix/* master Merge Commit Track emergency fixes
bugfix/* develop Squash Single bug fix commit

Release Tagging

Semantic Versioning

The project follows Semantic Versioning 2.0.0 (semver.org).

MAJOR.MINOR.PATCH

Examples:
v1.0.0  - Initial release
v1.0.1  - Hotfix (patch)
v1.1.0  - New features (minor)
v2.0.0  - Breaking changes (major)

Version Increment Rules

Version When to Increment Example
MAJOR Breaking changes, incompatible API changes 1.5.3 → 2.0.0
MINOR New features, backward-compatible 1.5.3 → 1.6.0
PATCH Bug fixes, backward-compatible 1.5.3 → 1.5.4

Creating a Release Tag

# Create annotated tag
git tag -a v1.0.0 -m "Release version 1.0.0

New Features:
- Product review system
- Advanced search
- Payment gateway integration

Bug Fixes:
- Cart calculation fix
- Image upload validation

Performance:
- Database index optimizations
- Caching improvements"

# Push tag to remote
git push origin v1.0.0

# Push all tags
git push origin --tags

Tag Naming Conventions

Type Format Example
Release v<major>.<minor>.<patch> v1.0.0, v2.1.3
Pre-release v<version>-<pre> v1.0.0-alpha.1, v2.0.0-beta.2
Build metadata v<version>+<build> v1.0.0+20250107

Changelog Management

Maintain a CHANGELOG.md file following the "Keep a Changelog" format.

CHANGELOG.md Structure

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Feature X for doing Y

### Changed
- Improved performance of Z

## [2.0.0] - 2025-01-15

### Added
- Advanced search functionality with filters
- Product review system with ratings
- Payment gateway integration (Stripe, PayPal)
- Redis caching for improved performance
- Audit logging for all user actions

### Changed
- Updated product API response format (BREAKING)
- Improved order processing workflow
- Enhanced error messages

### Fixed
- Cart quantity calculation error
- Image upload validation bug
- Stock management race condition

### Security
- Fixed JWT token validation issue
- Added rate limiting to prevent abuse

## [1.0.1] - 2024-12-20

### Fixed
- Payment processing null reference exception
- Order status update validation

### Security
- Patched SQL injection vulnerability in search

## [1.0.0] - 2024-12-01

### Added
- Initial release
- Product catalog management
- Shopping cart functionality
- Order processing
- User authentication and authorization
- Admin dashboard

[Unreleased]: https://github.com/org/shirinzad/compare/v2.0.0...HEAD
[2.0.0]: https://github.com/org/shirinzad/compare/v1.0.1...v2.0.0
[1.0.1]: https://github.com/org/shirinzad/compare/v1.0.0...v1.0.1
[1.0.0]: https://github.com/org/shirinzad/releases/tag/v1.0.0

Changelog Categories

  • Added: New features
  • Changed: Changes to existing functionality
  • Deprecated: Soon-to-be removed features
  • Removed: Removed features
  • Fixed: Bug fixes
  • Security: Security vulnerability fixes

Git Hooks for Automation

Pre-commit Hook

Automatically run checks before allowing commits.

#!/bin/sh
# .git/hooks/pre-commit

echo "Running pre-commit checks..."

# Check code formatting
echo "Checking code formatting..."
dotnet format --verify-no-changes
if [ $? -ne 0 ]; then
    echo "Code formatting check failed. Run 'dotnet format' to fix."
    exit 1
fi

# Run linter
echo "Running linter..."
dotnet build /warnaserror
if [ $? -ne 0 ]; then
    echo "Build warnings detected. Fix warnings before committing."
    exit 1
fi

# Run tests
echo "Running tests..."
dotnet test --no-build
if [ $? -ne 0 ]; then
    echo "Tests failed. Fix tests before committing."
    exit 1
fi

echo "All pre-commit checks passed!"
exit 0

Commit-msg Hook

Validate commit message format.

#!/bin/sh
# .git/hooks/commit-msg

commit_msg_file=$1
commit_msg=$(cat "$commit_msg_file")

# Check if commit message matches conventional commits format
conventional_commit_regex="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|security)(\(.+\))?: .{1,50}"

if ! echo "$commit_msg" | grep -qE "$conventional_commit_regex"; then
    echo "ERROR: Commit message does not follow Conventional Commits format"
    echo ""
    echo "Format: (): "
    echo ""
    echo "Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, security"
    echo ""
    echo "Example: feat(products): add product review system"
    exit 1
fi

exit 0

Using Husky for Git Hooks

Husky simplifies Git hook management in JavaScript/TypeScript projects.

# Install Husky (if using npm for front-end)
npm install husky --save-dev
npx husky install

# Add pre-commit hook
npx husky add .husky/pre-commit "dotnet format --verify-no-changes"
npx husky add .husky/pre-commit "dotnet test"

# Add commit-msg hook
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

Git Best Practices

Commit Best Practices

  • Make atomic commits (one logical change)
  • Write clear, descriptive commit messages
  • Commit early and often
  • Never commit broken code
  • Don't commit generated files or secrets
  • Review changes before committing

Branch Best Practices

  • Keep branches short-lived (days, not weeks)
  • Delete merged branches
  • Pull/rebase frequently from develop
  • Never force push to shared branches
  • Use descriptive branch names
  • Resolve conflicts locally before pushing

Collaboration Best Practices

  • Review pull requests promptly
  • Provide constructive feedback
  • Test changes locally before approving
  • Keep PRs small and focused
  • Communicate with team members
  • Document complex changes

Security Best Practices

  • Never commit passwords or API keys
  • Use .gitignore for sensitive files
  • Remove sensitive data from history if committed
  • Use SSH keys for authentication
  • Enable 2FA on GitHub account
  • Review dependencies for vulnerabilities

Common Git Commands Reference

Branch Management

# Create and switch to new branch
git checkout -b feature/new-feature

# Switch to existing branch
git checkout develop

# List all branches
git branch -a

# Delete local branch
git branch -d feature/old-feature

# Delete remote branch
git push origin --delete feature/old-feature

# Rename current branch
git branch -m new-name

Syncing Changes

# Fetch changes from remote
git fetch origin

# Pull changes and rebase
git pull --rebase origin develop

# Pull changes and merge
git pull origin develop

# Push changes
git push origin feature/branch

# Force push (use with caution!)
git push --force-with-lease origin branch

Undoing Changes

# Discard uncommitted changes
git checkout -- file.cs

# Unstage file
git reset HEAD file.cs

# Amend last commit
git commit --amend

# Revert a commit
git revert abc123

# Reset to previous commit (soft)
git reset --soft HEAD~1

# Reset to previous commit (hard, dangerous!)
git reset --hard HEAD~1

Viewing History

# View commit history
git log

# View compact history
git log --oneline

# View with graph
git log --oneline --graph --all

# View changes in commit
git show abc123

# View file history
git log -- path/to/file.cs

# Search commits
git log --grep="fix"

Related Documentation

CI/CD

Automated build and deployment pipelines

Testing

Unit and integration testing guide

Documentation

Documentation standards and guidelines