Git Conventions

Consistent Git practices enable smooth collaboration, clear history, and reliable deployments. These conventions are followed across all YeboLearn repositories.

Branch Naming

Feature Branches

bash

feature/ai-quiz-generator
feature/student-dashboard-redesign
feature/offline-mode

Pattern: feature/brief-description

Use lowercase with hyphens
Keep names concise but descriptive
Focus on the what, not the how

Bug Fix Branches

bash

fix/payment-timeout
fix/quiz-scoring-error
fix/login-redirect

Pattern: fix/issue-description

Clearly describe the issue being fixed
Reference issue number in PR description

Hotfix Branches

bash

hotfix/critical-payment-failure
hotfix/data-corruption-risk
hotfix/security-vulnerability

Pattern: hotfix/critical-issue

Only for production emergencies
Created from main branch
Fast-tracked review and deployment

Experimental Branches

bash

experiment/gemini-2-integration
experiment/redis-caching
experiment/new-ui-framework

Pattern: experiment/description

For proof-of-concepts and spikes
Not intended for production
Share learnings, then delete

Commit Messages

Conventional Commits

We follow Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer]

Commit Types

feat: New feature

bash

feat(ai): add essay auto-grading with Gemini
feat(payments): integrate M-Pesa payment gateway
feat(analytics): add student progress dashboard

fix: Bug fix

bash

fix(auth): resolve token expiration edge case
fix(quiz): correct scoring calculation for partial answers
fix(api): handle rate limit errors gracefully

docs: Documentation only

bash

docs(api): update authentication endpoint examples
docs(setup): add Docker installation instructions
docs(readme): update feature list

style: Code style changes (formatting, no logic change)

bash

style(components): apply Prettier formatting
style(api): fix ESLint warnings
style(types): organize TypeScript interfaces

refactor: Code restructuring (no feature or bug change)

bash

refactor(auth): extract validation logic to separate module
refactor(db): optimize database query structure
refactor(components): migrate to React hooks

perf: Performance improvement

bash

perf(api): add Redis caching for quiz data
perf(db): add indexes for common queries
perf(frontend): lazy load AI features

test: Adding or updating tests

bash

test(ai): add unit tests for quiz generator
test(payments): add integration tests for M-Pesa
test(e2e): add critical user flow tests

build: Build system or dependencies

bash

build(deps): upgrade React to v19
build(docker): optimize production image size
build(ci): add bundle size checking

ci: CI/CD configuration

bash

ci(github): add automated security scanning
ci(deploy): configure staging environment
ci(tests): parallelize test execution

chore: Maintenance tasks

bash

chore(deps): update development dependencies
chore(config): update ESLint rules
chore(cleanup): remove deprecated API endpoints

Commit Message Examples

Good Commits:

bash

feat(ai): implement real-time essay feedback
- Integrate Gemini API for essay analysis
- Add streaming response support
- Include grammar and structure suggestions
- Add rate limiting to prevent API overuse

fix(payments): resolve duplicate transaction issue
- Add idempotency key validation
- Implement transaction deduplication
- Add comprehensive error logging
- Fixes #234

perf(db): optimize student progress queries
- Add composite index on (student_id, course_id)
- Reduce query time from 800ms to 45ms
- Update related API endpoints

Bad Commits:

bash

# Too vague
Update files
Fix bug
Changes

# No type prefix
Added new feature
Fixed the login issue

# Too long subject
feat(ai): implement the new AI-powered quiz generator that uses Google Gemini to create personalized quizzes based on student performance and learning patterns

Commit Best Practices

Write Clear Subjects

Use imperative mood: "add feature" not "added feature"
Keep subject line ≤50 characters
Don't end with period
Capitalize first letter

Provide Context in Body

Explain why the change was made
Describe what problem it solves
Reference issues: "Fixes #123", "Closes #456"
Include breaking changes: "BREAKING CHANGE: API endpoint renamed"

Make Atomic Commits

One logical change per commit
Should be independently reviewable
Tests should pass after each commit
Makes git bisect effective

Pull Request Workflow

Creating Pull Requests

PR Title Format:

feat(ai): Add AI quiz generator
fix(auth): Resolve token refresh issue
perf(api): Optimize database queries

Follow same conventions as commit messages
Clear and descriptive
Indicate scope and impact

PR Description Template:

markdown

## Summary
Brief description of what this PR does and why.

## Changes
- Specific change 1
- Specific change 2
- Specific change 3

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests passing
- [ ] Manually tested in dev environment
- [ ] Edge cases considered

## Screenshots (if UI changes)
[Add screenshots here]

## Related Issues
Fixes #123
Relates to #456

## Deployment Notes
Any special deployment considerations, database migrations, etc.

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No console errors or warnings
- [ ] Tested on multiple browsers (if frontend)

PR Labels

Type Labels:

feature - New functionality
bugfix - Bug fixes
hotfix - Critical production fix
refactor - Code restructuring
documentation - Docs only

Status Labels:

in-progress - Still being developed
ready-for-review - Ready for review
needs-changes - Reviewer requested changes
approved - Approved and ready to merge

Priority Labels:

critical - Production emergency
high - Important for current sprint
medium - Standard priority
low - Nice to have

Domain Labels:

ai - AI features
payments - Payment processing
frontend - UI/UX changes
backend - API/database changes
infrastructure - DevOps/deployment

Review Process

For Authors:

Before Creating PR:
- All tests passing locally
- Code is self-reviewed
- Documentation updated
- Commits are clean and logical
Create PR:
- Use template and fill all sections
- Add appropriate labels
- Request specific reviewers if needed
- Link related issues
During Review:
- Respond to feedback promptly
- Explain design decisions
- Make requested changes
- Re-request review after changes
After Approval:
- Ensure CI is green
- Squash commits if many small fixes
- Merge to target branch
- Delete feature branch

For Reviewers:

Review Within 4 Hours:
- Check notification regularly
- Prioritize team PRs
Review Checklist:
- Code quality and readability
- Test coverage and quality
- Performance implications
- Security considerations
- API consistency
- Documentation completeness
Provide Constructive Feedback:
- Explain the "why" behind suggestions
- Distinguish between required changes and suggestions
- Acknowledge good work
- Ask questions to understand intent
Approve or Request Changes:
- Be explicit about what's needed
- Re-review promptly after changes

PR Size Guidelines

Small PR (Preferred):

<200 lines changed
Single feature or fix
Quick to review
Low risk

Medium PR:

200-500 lines changed
Multiple related changes
Requires focused review time
Moderate risk

Large PR (Avoid):

500 lines changed
Should be split into smaller PRs
Hard to review thoroughly
High risk of issues

Handling Large Changes:

Break into multiple PRs
Use feature flags for partial releases
Create RFC document first
Do incremental merges

Merge Strategies

Squash and Merge (Default)

When to Use:

Feature branches to dev
Multiple small commits
Want clean history

Result:

bash

# Before merge (feature branch)
feat: add API endpoint
fix: typo in response
fix: address review feedback
test: add missing test

# After merge (dev branch)
feat(ai): add quiz generator API endpoint (#234)

Benefits:

Clean, linear history
Easy to revert entire features
Meaningful commit messages

Rebase and Merge

When to Use:

Well-structured commit history
Each commit is meaningful
Want to preserve commit detail

Result:

bash

# All commits from feature branch appear in dev
feat(ai): add quiz generator endpoint
feat(ai): integrate Gemini API
test(ai): add quiz generator tests
docs(ai): document quiz API

Benefits:

Detailed history
Good for git bisect
Shows development progression

Regular Merge (Rarely)

When to Use:

Merging long-lived branches (staging → main)
Want to preserve branch context

Avoid For:

Feature branches (creates messy history)

Release Tagging

Semantic Versioning

We follow Semantic Versioning: MAJOR.MINOR.PATCH

v2.4.1
│ │ │
│ │ └── PATCH: Bug fixes, no new features
│ └──── MINOR: New features, backward compatible
└────── MAJOR: Breaking changes

Version Incrementing

PATCH (v2.4.0 → v2.4.1):

Bug fixes only
Performance improvements
Documentation updates
Security patches

MINOR (v2.4.1 → v2.5.0):

New AI features
New API endpoints (backward compatible)
Enhanced existing features
Non-breaking refactors

MAJOR (v2.5.0 → v3.0.0):

Breaking API changes
Major architecture changes
Database schema breaking changes
Removed deprecated features

Creating Release Tags

Bi-Weekly Release Process:

bash

# Ensure on main branch
git checkout main
git pull origin main

# Create annotated tag
git tag -a v2.5.0 -m "Release v2.5.0: AI Essay Grading

Features:
- AI-powered essay grading
- Real-time feedback system
- Student progress analytics

Improvements:
- Quiz loading performance (40% faster)
- Payment processing reliability

Bug Fixes:
- Fixed login redirect issue
- Resolved quiz scoring edge case
"

# Push tag to remote
git push origin v2.5.0

Tag Message Format:

Release v2.5.0: Feature Highlight

Features:
- Feature 1
- Feature 2

Improvements:
- Improvement 1
- Improvement 2

Bug Fixes:
- Fix 1
- Fix 2

Hotfix Tags

bash

# For critical production fixes
git tag -a v2.5.1 -m "Hotfix v2.5.1: Payment timeout fix

Critical Fix:
- Resolved payment processor timeout issue
- Added retry logic with exponential backoff
- Improved error logging
"

git push origin v2.5.1

Pre-Release Tags

bash

# For beta testing
v2.6.0-beta.1
v2.6.0-beta.2
v2.6.0-rc.1  # Release candidate

Branch Protection Rules

Main Branch (Production)

Required:

At least 1 approving review
All status checks must pass
Branch must be up to date
No force pushes
No deletions

Status Checks:

All tests passing
Linting passing
Build successful
Security scan clean

Staging Branch

Required:

At least 1 approving review
All tests passing
No force pushes

Dev Branch

Required:

All tests passing
No force pushes (use revert instead)

Git Best Practices

Daily Workflow

Start of Day:

bash

git checkout dev
git pull origin dev
git checkout feature/my-feature
git rebase dev  # Keep feature branch current

During Development:

bash

# Commit regularly with good messages
git add src/features/ai-quiz.ts
git commit -m "feat(ai): implement quiz generation logic"

# Push regularly to backup work
git push origin feature/my-feature

End of Day:

bash

# Ensure work is pushed
git push origin feature/my-feature

# Update local dev branch for next day
git checkout dev
git pull origin dev

Keeping Branches Current

bash

# Rebase feature branch with latest dev
git checkout feature/my-feature
git fetch origin
git rebase origin/dev

# Resolve conflicts if any
# ... fix conflicts ...
git add .
git rebase --continue

# Force push after rebase (your branch only!)
git push --force-with-lease origin feature/my-feature

Undoing Mistakes

Undo Last Commit (Not Pushed):

bash

git reset --soft HEAD~1  # Keep changes
git reset --hard HEAD~1  # Discard changes

Revert Commit (Already Pushed):

bash

git revert <commit-hash>  # Creates new commit

Discard Local Changes:

bash

git checkout -- file.ts  # Single file
git reset --hard HEAD    # All files

Common Scenarios

Scenario 1: Starting New Feature

bash

# Update dev branch
git checkout dev
git pull origin dev

# Create feature branch
git checkout -b feature/ai-study-planner

# Develop and commit
# ... make changes ...
git add .
git commit -m "feat(ai): implement study plan generation"

# Push and create PR
git push -u origin feature/ai-study-planner
# Create PR in GitHub UI

Scenario 2: Addressing PR Feedback

bash

# Make requested changes
# ... fix code ...
git add .
git commit -m "fix(ai): handle edge case in study planner"

# Push changes
git push origin feature/ai-study-planner

# Re-request review in GitHub

Scenario 3: Emergency Hotfix

bash

# Create from production
git checkout main
git pull origin main
git checkout -b hotfix/payment-failure

# Fix and test thoroughly
# ... fix issue ...
git commit -m "fix(payments): resolve transaction timeout

- Add retry logic with exponential backoff
- Increase timeout from 5s to 15s
- Add comprehensive error logging
- Fixes #789
"

# Fast-track review and merge to main
git push origin hotfix/payment-failure

# After merge, backport to staging and dev
git checkout staging
git cherry-pick <hotfix-commit-hash>
git push origin staging

git checkout dev
git cherry-pick <hotfix-commit-hash>
git push origin dev

Git Configuration

Recommended Git Config

bash

# User information
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Default branch name
git config --global init.defaultBranch main

# Helpful aliases
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.st status
git config --global alias.cm commit
git config --global alias.lg "log --graph --oneline --decorate --all"

# Rebase by default when pulling
git config --global pull.rebase true

# Prune deleted remote branches
git config --global fetch.prune true

Resources

Development Workflow - Overall workflow overview
Code Review Process - Detailed review guidelines
Deployment Process - Release and deployment

Git Conventions ​

Branch Naming ​

Feature Branches ​

Bug Fix Branches ​

Hotfix Branches ​

Experimental Branches ​

Commit Messages ​

Conventional Commits ​

Commit Types ​

Commit Message Examples ​

Commit Best Practices ​

Pull Request Workflow ​

Creating Pull Requests ​

PR Labels ​

Review Process ​

PR Size Guidelines ​

Merge Strategies ​

Squash and Merge (Default) ​

Rebase and Merge ​

Regular Merge (Rarely) ​

Release Tagging ​

Semantic Versioning ​

Version Incrementing ​

Creating Release Tags ​

Hotfix Tags ​

Pre-Release Tags ​

Branch Protection Rules ​

Main Branch (Production) ​

Staging Branch ​

Dev Branch ​

Git Best Practices ​

Daily Workflow ​

Keeping Branches Current ​

Undoing Mistakes ​

Common Scenarios ​

Scenario 1: Starting New Feature ​

Scenario 2: Addressing PR Feedback ​

Scenario 3: Emergency Hotfix ​

Git Configuration ​

Recommended Git Config ​

Resources ​

Related Documentation ​

Git Conventions

Branch Naming

Feature Branches

Bug Fix Branches

Hotfix Branches

Experimental Branches

Commit Messages

Conventional Commits

Commit Types

Commit Message Examples

Commit Best Practices

Pull Request Workflow

Creating Pull Requests

PR Labels

Review Process

PR Size Guidelines

Merge Strategies

Squash and Merge (Default)

Rebase and Merge

Regular Merge (Rarely)

Release Tagging

Semantic Versioning

Version Incrementing

Creating Release Tags

Hotfix Tags

Pre-Release Tags

Branch Protection Rules

Main Branch (Production)

Staging Branch

Dev Branch

Git Best Practices

Daily Workflow

Keeping Branches Current

Undoing Mistakes

Common Scenarios

Scenario 1: Starting New Feature

Scenario 2: Addressing PR Feedback

Scenario 3: Emergency Hotfix

Git Configuration

Recommended Git Config

Resources

Related Documentation