🔧 Git Workflow & Conventional Commits

This guide covers our Git workflow and commit message standards for the CLOE Toolbox project.

🌿 Git Workflow

Branch Strategy

We use a feature branch workflow integrated with Azure DevOps:

graph LR
    A[main] --> B[feature/auth-module]
    B --> C[feat: add login]
    C --> D[test: add auth tests]
    D --> E[docs: update API docs]
    E --> F[merge to main]
    F --> G[v1.2.0]
    A --> H[hotfix/security-patch]
    H --> I[fix: security vulnerability]
    I --> J[merge to main]
    J --> K[v1.2.1]

🏗️ Branch Naming Convention

Use descriptive branch names that clearly indicate the purpose:

Branch Type	Pattern	Example
🆕 Features	feature/description	feature/user-authentication
🐛 Bug Fixes	fix/description	fix/memory-leak-processor
📚 Documentation	docs/description	docs/api-reference
🔧 Maintenance	chore/description	chore/update-dependencies
🚨 Hotfixes	hotfix/description	hotfix/security-patch

📝 Conventional Commits

We follow the Conventional Commits specification for consistent commit messages.

🎯 Commit Message Format

<type>[optional scope]: <description> [#work-item-id]

[optional body]

[optional footer(s)]

📋 Commit Types

Type	Description	Example
feat	✨ New feature	feat: add user login functionality #1234
fix	🐛 Bug fix	fix: resolve memory leak in data processor #1235
docs	📚 Documentation	docs: add API reference for auth module #1236
style	💄 Code style changes	style: format code according to PEP 8 #1237
refactor	♻️ Code refactoring	refactor: simplify user validation logic #1238
test	🧪 Adding tests	test: add unit tests for auth module #1239
chore	🔧 Maintenance	chore: update dependencies to latest versions #1240
perf	⚡ Performance improvements	perf: optimize database query performance #1241
ci	👷 CI/CD changes	ci: add automated security scanning #1242
build	📦 Build system changes	build: update build configuration #1243

🔍 Scope (Optional)

Specify the component or module affected:

feat(auth): add OAuth2 integration #1234
fix(database): resolve connection timeout issue #1235
docs(api): update endpoint documentation #1236

💡 Commit Examples

✨ Feature Addition🐛 Bug Fix📚 Documentation🔧 Breaking Change

feat: add user authentication module #1234

- Implement login/logout functionality
- Add password hashing with bcrypt
- Include session management

Closes #1234

fix: resolve memory leak in data processor #1235

The data processor was not properly cleaning up resources
after processing large datasets, causing memory usage to grow
continuously.

- Add proper resource cleanup in finally blocks
- Implement garbage collection hints
- Add memory usage monitoring

Fixes #1235

docs: add comprehensive API reference #1236

- Document all public endpoints
- Add request/response examples
- Include error code documentation

feat!: update user model structure #1237

BREAKING CHANGE: User model now requires email field

The user model has been updated to require an email field
for improved user identification and communication.

Migration required for existing data.

🔗 Azure DevOps Integration

📎 Linking Work Items

Always link commits to Azure DevOps work items using the ID:

# Feature commits
git commit -m "feat: implement data validation #1234"

# Multiple work items
git commit -m "fix: resolve authentication issues #1234 #1235"

# Different linking keywords
git commit -m "feat: add new endpoint (closes #1234)"
git commit -m "fix: memory leak (fixes #1235)"
git commit -m "docs: API reference (resolves #1236)"

🏷️ Keywords for Work Item Actions

Keyword	Action	Usage
#1234	Link	Links commit to work item
fixes #1234	Close	Closes work item when merged
closes #1234	Close	Closes work item when merged
resolves #1234	Close	Closes work item when merged

🛠️ Git Best Practices

📦 Commit Guidelines

• 🎯 Atomic Commits: Each commit should represent a single logical change
• 📝 Clear Messages: Write descriptive commit messages for future developers
• 🔗 Link Work Items: Always include Azure DevOps work item IDs
• 📏 Reasonable Size: Keep commits focused and reasonably sized

🔄 Before Committing

1. 🧪 Run Tests: Ensure all tests pass

pytest tests/

1. 🧹 Check Code Quality: Run linting and formatting

black src/
flake8 src/
mypy src/

1. 📖 Update Documentation: Update relevant documentation

2. 📋 Review Changes: Double-check what you're committing

git diff --staged

🌊 Git Flow Commands

🚀 Starting New Work

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

# Link initial commit to work item
git commit -m "feat: initial setup for new feature #1234"

💾 Regular Development

# Stage specific files
git add src/module.py tests/test_module.py

# Commit with conventional format
git commit -m "feat: add data validation logic #1234"

# Push to remote
git push origin feature/your-feature-name

🔄 Preparing for PR

# Rebase on latest main
git fetch origin
git rebase origin/main

# Interactive rebase to clean up commits (if needed)
git rebase -i origin/main

# Force push (only for feature branches)
git push --force-with-lease origin feature/your-feature-name

🚀 Advanced Git Techniques

🔧 Interactive Rebase

Use interactive rebase to clean up commit history before creating PRs:

# Rebase last 3 commits interactively
git rebase -i HEAD~3

# Common rebase commands:
# pick    = use commit
# reword  = use commit, but edit message
# edit    = use commit, but stop for amending
# squash  = use commit, but meld into previous commit
# drop    = remove commit

🎯 Cherry-picking

Apply specific commits to other branches:

# Apply commit to current branch
git cherry-pick <commit-hash>

# Apply multiple commits
git cherry-pick <commit1> <commit2>

🔍 Useful Git Commands

# View commit history with graph
git log --oneline --graph --decorate

# Search commit messages
git log --grep="feat"

# Find when a bug was introduced
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>

# Show changes in a commit
git show <commit-hash>

# Compare branches
git diff main..feature/branch-name

---

Pro Tips

• Use git commit --amend to modify the last commit message
• Create aliases for frequently used commands in .gitconfig
• Use git stash to temporarily save work when switching branches
• Set up VS Code as your default Git editor for better commit message writing

Important Reminders

• Never force push to main branch
• Always include work item IDs in commit messages
• Keep commit messages under 72 characters for the first line
• Use present tense in commit messages ("add" not "added")