Version Control Guidelines

Overview

This document defines GitHub usage standards and best practices for our SaaS CRM application development team.

Repository Structure

Main Repositories

github.com/ourcompany/
├── crm-frontend/          # Nuxt 4 application
├── crm-backend/           # PHP Phalcon API
├── crm-database/          # Database schemas and migrations
├── crm-infrastructure/    # Docker, K8s, CI/CD configs
├── crm-documentation/     # This documentation
└── crm-tests/            # E2E and integration tests

Repository Settings

Branch Protection Rules

main branch: Protected, requires PR
develop branch: Protected, requires PR
feature branches: No direct commits to main
Require: 2 approvals for main, 1 for develop
Enforce: All checks must pass
Dismiss stale reviews: When new commits pushed

Branching Strategy

GitFlow Model

gitGraph
    commit
    branch develop
    checkout develop
    commit
    branch feature/CRM-123
    checkout feature/CRM-123
    commit
    commit
    checkout develop
    merge feature/CRM-123
    branch release/v1.2.0
    checkout release/v1.2.0
    commit
    checkout main
    merge release/v1.2.0
    checkout develop
    merge release/v1.2.0

Branch Types

1. Main Branches

Branch	Purpose	Deployment
`main`	Production-ready code	Production
`develop`	Integration branch	Staging

2. Supporting Branches

Type	Naming	Created From	Merged To	Example
Feature	`feature/CRM-XXX-description`	develop	develop	`feature/CRM-123-user-auth`
Bugfix	`bugfix/CRM-XXX-description`	develop	develop	`bugfix/CRM-456-login-error`
Release	`release/vX.Y.Z`	develop	main + develop	`release/v1.2.0`
Hotfix	`hotfix/CRM-XXX-description`	main	main + develop	`hotfix/CRM-789-critical-fix`

Branch Naming Conventions

# Format: type/ticket-description

# Good examples:
feature/CRM-123-add-user-authentication
bugfix/CRM-456-fix-password-reset
hotfix/CRM-789-patch-security-vulnerability
release/v2.1.0

# Bad examples (avoid):
feature/new-feature
bugfix/fix-bug
my-branch
test

Commit Guidelines

Commit Message Format

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

<body>

<footer>

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, semicolons, etc.)
refactor: Code refactoring
perf: Performance improvements
test: Test additions or corrections
build: Build system changes
ci: CI/CD changes
chore: Maintenance tasks
revert: Revert previous commit

Examples

# Feature commit
feat(auth): implement two-factor authentication

Add TOTP-based 2FA with QR code generation and backup codes.
Includes rate limiting and brute force protection.

Closes #123

# Bug fix commit
fix(api): resolve memory leak in customer endpoint

The customer list endpoint was not properly releasing database
connections, causing memory leak under high load.

Fixes #456

# Documentation commit
docs(api): update authentication endpoint documentation

Add examples for new OAuth2 flow and update response schemas.

Commit Best Practices

Atomic Commits: One logical change per commit
Present Tense: Use "add" not "added"
Imperative Mood: "Fix bug" not "Fixed bug"
Line Length: Subject ≤ 50 chars, body ≤ 72 chars
Reference Issues: Include ticket numbers

Pull Request Process

Creating a Pull Request

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix (non-breaking change)
- [ ] New feature (non-breaking change)
- [ ] Breaking change (fix or feature with breaking changes)
- [ ] Documentation update

## Related Issue
Closes #(issue number)

## Changes Made
- Change 1
- Change 2
- Change 3

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

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

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

PR Review Process

Review Checklist

Code Quality - [ ] Code is readable and maintainable - [ ] Follows coding standards - [ ] No code duplication - [ ] Proper error handling - [ ] Appropriate logging

Functionality - [ ] Meets requirements - [ ] Edge cases handled - [ ] Backward compatible - [ ] Performance acceptable - [ ] Security considered

Testing - [ ] Adequate test coverage - [ ] Tests are meaningful - [ ] Edge cases tested - [ ] Integration tests included

Documentation - [ ] Code comments where needed - [ ] API documentation updated - [ ] README updated if needed - [ ] Changelog updated

Review Comments

Effective Review Comments

# Good comment:
"This query could cause N+1 problem. Consider using eager loading:
```php
$customers = Customer::with('orders')->get();
```"

# Bad comment:
"This is wrong"

Comment Prefixes

[MUST]: Required change
[SHOULD]: Strongly recommended
[CONSIDER]: Suggestion for improvement
[NITPICK]: Minor style issue
[QUESTION]: Clarification needed
[PRAISE]: Good code recognition

Merging Strategy

Merge Methods

Method	When to Use	Pros	Cons
Merge Commit	Feature branches	Preserves history	Cluttered history
Squash & Merge	Small features/fixes	Clean history	Loses granular commits
Rebase & Merge	Linear history needed	Clean timeline	Rewrites history

Default Strategy

Feature → Develop: Squash & Merge
Bugfix → Develop: Squash & Merge
Release → Main: Merge Commit (preserve history)
Hotfix → Main: Merge Commit

Git Workflow Commands

Daily Workflow

# Start new feature
git checkout develop
git pull origin develop
git checkout -b feature/CRM-123-new-feature

# Make changes
git add .
git commit -m "feat(module): add new functionality"

# Update with latest develop
git checkout develop
git pull origin develop
git checkout feature/CRM-123-new-feature
git rebase develop

# Push changes
git push origin feature/CRM-123-new-feature

# Create PR via GitHub UI

Handling Conflicts

# During rebase
git rebase develop
# Fix conflicts in files
git add .
git rebase --continue

# Or abort if needed
git rebase --abort

Emergency Hotfix

# Create hotfix from main
git checkout main
git pull origin main
git checkout -b hotfix/CRM-999-critical-fix

# Make fix
git add .
git commit -m "fix(critical): resolve production issue"

# Push and create PR
git push origin hotfix/CRM-999-critical-fix

# After merge, update develop
git checkout develop
git pull origin develop
git merge main
git push origin develop

Code Review Culture

For Authors

Self-Review First: Review your own PR before requesting
Small PRs: Keep PRs focused and small (<400 lines)
Context: Provide clear description and testing steps
Responsive: Address feedback promptly
Professional: Don't take feedback personally

For Reviewers

Timely: Review within 4 hours for urgent, 24 hours normal
Constructive: Provide actionable feedback
Positive: Acknowledge good code
Educational: Share knowledge and best practices
Pragmatic: Balance perfection with delivery

Security Practices

Sensitive Data

NEVER commit: - API keys - Passwords - Database credentials - SSL certificates - Customer data - Internal IP addresses

Secrets Management

# Use environment variables
.env.local  # Never commit
.env.example  # Commit with dummy values

# Example .env.example
DATABASE_HOST=localhost
DATABASE_USER=dbuser
DATABASE_PASS=changeme
API_KEY=your-api-key-here

Security Scanning

Pre-commit hooks: Detect secrets
Dependency scanning: Check vulnerabilities
Code scanning: Static analysis
License compliance: Verify licenses

Git Hooks

Pre-commit Hook

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

# Run linting
npm run lint
if [ $? -ne 0 ]; then
    echo "Linting failed. Please fix errors."
    exit 1
fi

# Run tests
npm test
if [ $? -ne 0 ]; then
    echo "Tests failed. Please fix."
    exit 1
fi

Commit-msg Hook

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

# Check commit message format
commit_regex='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .{1,50}'

if ! grep -qE "$commit_regex" "$1"; then
    echo "Invalid commit message format!"
    echo "Format: type(scope): subject"
    exit 1
fi

Repository Maintenance

Cleaning Up

# Delete merged branches
git branch --merged | grep -v "\*\|main\|develop" | xargs -n 1 git branch -d

# Prune remote branches
git remote prune origin

# Clean up old tags
git tag -l | xargs git tag -d
git fetch --tags

Archiving

Archive branches older than 6 months
Keep release branches for 1 year
Tag important milestones
Document archived branches

Tools & Integration

GitHub Integration

Issues: Link commits to issues
Projects: Track feature progress
Actions: Automated workflows
Webhooks: Teams notifications
Apps: Security scanning, code quality

IDE Integration

VS Code: GitLens extension
PhpStorm: Built-in Git support
Command Line: Git aliases for efficiency

Git Aliases

# Add to ~/.gitconfig
[alias]
    co = checkout
    br = branch
    ci = commit
    st = status
    unstage = reset HEAD --
    last = log -1 HEAD
    visual = !gitk
    history = log --oneline --graph --decorate --all

Troubleshooting

Common Issues

Issue	Solution
Merge conflicts	Rebase on latest develop
Large files	Use Git LFS
Accidental commit	`git reset --soft HEAD~1`
Wrong branch	Cherry-pick to correct branch
Lost commits	Check `git reflog`

Last Updated: January 2025 Version: 1.0.0