Git Workflow Strategy

This document outlines the commit, PR, and branch strategy for maintaining a clean, traceable git history with proper Jira integration.

Commit Strategy

Core Principles

• One commit per ticket: Each Jira ticket should result in exactly one commit
• Atomic commits: Each commit should represent a complete, logical unit of work
• Always link to Jira: Every commit must reference its Jira ticket ID

Commit Message Format

<type>(MSP2-XX): <description>

[Optional body with more details]

[Optional footer with breaking changes or additional ticket references]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring without functional changes
• test: Adding or updating tests
• chore: Maintenance tasks, dependency updates
• perf: Performance improvements
• style: Code style/formatting changes

Examples

# Feature commit
feat(MSP2-123): Add user authentication module

Implements JWT-based authentication with refresh tokens.
Includes login, logout, and token refresh endpoints.

# Bug fix commit
fix(MSP2-124): Resolve memory leak in data processing pipeline

Fixed unclosed database connections in batch processor.

# Documentation commit
docs(MSP2-125): Update API documentation for v2 endpoints

# Refactoring commit
refactor(MSP2-126): Extract validation logic into separate service

Best Practices

• Keep the subject line under 72 characters
• Use imperative mood ("Add feature" not "Added feature")
• Capitalize the first letter of the description
• No period at the end of the subject line
• Use the body to explain "what" and "why", not "how"

PR Strategy

Core Principles

• Multiple related tickets per PR: Group logically related tickets together
• Preserve commit history: Use merge commits, not squash
• Functional grouping: Organize PRs by feature area or sprint goal

When to Group Tickets

Group tickets in a single PR when they:

• Belong to the same feature or epic
• Share the same functional area
• Have dependencies on each other
• Are part of the same sprint deliverable

When to Separate PRs

Create separate PRs when tickets:

• Belong to different functional areas
• Can be deployed independently
• Have different reviewers or stakeholders
• Represent different priorities or timelines

PR Title Format

[MSP2-XX, MSP2-YY, MSP2-ZZ] Feature Area: High-level description

PR Description Template

## Summary
Brief overview of what this PR accomplishes

## Tickets Included
- MSP2-XX: Description of ticket
- MSP2-YY: Description of ticket
- MSP2-ZZ: Description of ticket

## Changes
- High-level change 1
- High-level change 2
- High-level change 3

## Testing
How this was tested and what scenarios were covered

## Deployment Notes
Any special considerations for deployment

## Related PRs
Links to related or dependent PRs

Merge Strategy

Always use merge commits, never squash:

# Correct: Merge with commit history preserved
git checkout main
git merge --no-ff feature-branch

# Incorrect: Squash loses individual commit history
git merge --squash feature-branch  #  Don't do this

Why preserve commits?

• Maintains traceability to individual Jira tickets
• Allows cherry-picking specific fixes
• Provides granular history for debugging
• Enables better git bisect operations

Branch Strategy

Branch Types

main
 dev
     feature/MSP2-123-user-auth
     feature/MSP2-124-payment-integration
     feature/MSP2-125-reporting-dashboard

Branch Descriptions

main

• Production-ready code only
• Protected branch with required reviews
• All code must pass CI/CD before merge
• Tagged with version numbers for releases

dev

• Integration branch for ongoing development
• All feature work merges here first
• Should always be in a deployable state
• Regularly merged to main for releases

feature/MSP2-XX-description

• Individual feature branches (optional)
• Created when working on isolated features
• Named with ticket ID and brief description
• Deleted after merge to dev

Branch Naming Convention

# Feature branches
feature/MSP2-123-user-authentication
feature/MSP2-124-payment-gateway

# Bug fix branches (if needed)
fix/MSP2-125-login-error

# Hotfix branches (for production issues)
hotfix/MSP2-126-critical-security-patch

Workflow Process

Scenario 1: Starting Fresh with Individual Commits

When starting a new feature or working on tickets:

# 1. Create feature branch from dev
git checkout dev
git pull origin dev
git checkout -b feature/MSP2-123-user-auth

# 2. Make changes for MSP2-123
# ... code changes ...

# 3. Commit with proper message
git add .
git commit -m "feat(MSP2-123): Add user authentication module"

# 4. Push to remote
git push origin feature/MSP2-123-user-auth

# 5. Create PR to dev
# PR Title: [MSP2-123] Authentication: Add user authentication module

Scenario 2: Splitting Existing Dev Branch into Individual Commits

When you have multiple changes in dev that need to be split into individual commits:

# 1. Create a backup branch
git checkout dev
git branch dev-backup

# 2. Create a new clean branch from the last good state
git checkout -b dev-reorganized origin/main

# 3. For each ticket, cherry-pick or create individual commits
# Option A: If changes are already committed but mixed
git checkout dev-backup
git log --oneline  # Review commits

# Create feature branch for first ticket
git checkout dev-reorganized
git checkout -b feature/MSP2-123-ticket-one

# Cherry-pick relevant commits or manually apply changes
git cherry-pick <commit-hash>
# OR manually copy files and commit
git add <files-for-MSP2-123>
git commit -m "feat(MSP2-123): Description"

# 4. Repeat for each ticket
git checkout dev-reorganized
git checkout -b feature/MSP2-124-ticket-two
# ... apply changes for MSP2-124 ...
git commit -m "feat(MSP2-124): Description"

# 5. Create PRs for each feature branch or group related ones

Scenario 3: Creating PRs from Multiple Commits

When you have several related commits ready for review:

# 1. Ensure all commits are on dev
git checkout dev
git log --oneline -10  # Review recent commits

# 2. Create PR branch with multiple commits
git checkout -b pr/authentication-module

# 3. Ensure commits are clean and properly formatted
git log --oneline

# Expected output:
# abc1234 feat(MSP2-125): Add password reset functionality
# def5678 feat(MSP2-124): Add JWT token refresh
# ghi9012 feat(MSP2-123): Add user authentication module

# 4. Push and create PR
git push origin pr/authentication-module

# 5. Create PR with title:
# [MSP2-123, MSP2-124, MSP2-125] Authentication: Complete user authentication system

Scenario 4: Maintaining Linear History

To keep history clean and linear:

# 1. Before merging feature to dev, rebase on latest dev
git checkout feature/MSP2-123-user-auth
git fetch origin
git rebase origin/dev

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

# 3. Force push (only on feature branches, never on main/dev)
git push --force-with-lease origin feature/MSP2-123-user-auth

# 4. Merge to dev with merge commit
git checkout dev
git merge --no-ff feature/MSP2-123-user-auth
git push origin dev

Scenario 5: Hotfix Workflow

For urgent production fixes:

# 1. Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/MSP2-126-critical-fix

# 2. Make the fix
# ... code changes ...
git add .
git commit -m "fix(MSP2-126): Resolve critical security vulnerability"

# 3. Create PR to main
git push origin hotfix/MSP2-126-critical-fix
# Create PR: [MSP2-126] Hotfix: Critical security patch

# 4. After merge to main, also merge to dev
git checkout dev
git merge main
git push origin dev

Traceability and History

Viewing Commit History by Ticket

# Find all commits for a specific ticket
git log --all --grep="MSP2-123"

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

# View commits by author
git log --author="John Doe" --oneline

Linking Commits to Jira

Jira automatically links commits when:

• Commit message contains ticket ID (MSP2-XX)
• Repository is connected to Jira
• Proper integration is configured

View linked commits in Jira:

1. Open ticket (e.g., MSP2-123)
2. Navigate to "Development" panel
3. See all linked commits, branches, and PRs

Cherry-picking Specific Fixes

# Find the commit for a specific ticket
git log --all --grep="MSP2-124" --oneline

# Cherry-pick to another branch
git checkout target-branch
git cherry-pick <commit-hash>

Reverting Changes by Ticket

# Revert a specific ticket's commit
git log --all --grep="MSP2-123" --oneline
git revert <commit-hash>
git commit -m "revert(MSP2-123): Revert user authentication changes"

Common Workflows Summary

Daily Development Flow

# Morning: Update your branch
git checkout dev
git pull origin dev

# Work on ticket
git checkout -b feature/MSP2-XXX-description
# ... make changes ...
git add .
git commit -m "feat(MSP2-XXX): Description"
git push origin feature/MSP2-XXX-description

# Create PR to dev
# After approval and merge, delete feature branch
git branch -d feature/MSP2-XXX-description

Sprint End Flow

# Review all commits in dev
git checkout dev
git log --oneline origin/main..HEAD

# Group related commits into PR
git checkout -b pr/sprint-X-features

# Create PR from dev to main
# Title: [MSP2-XX, MSP2-YY, MSP2-ZZ] Sprint X: Feature delivery

Release Flow

# Create release branch from main
git checkout main
git pull origin main
git checkout -b release/v1.2.0

# Tag the release
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

# Merge release to main
git checkout main
git merge --no-ff release/v1.2.0
git push origin main

Best Practices Checklist

Before Committing

• [ ] Changes are complete and tested
• [ ] Commit message follows format: type(MSP2-XX): Description
• [ ] Commit is atomic (one logical change)
• [ ] No unrelated changes included
• [ ] Code passes linting and tests

Before Creating PR

• [ ] All commits have proper Jira ticket references
• [ ] Commits are logically grouped
• [ ] Branch is rebased on latest dev/main
• [ ] PR description is complete
• [ ] Related tickets are listed
• [ ] Tests are passing

Before Merging PR

• [ ] Code review is approved
• [ ] CI/CD checks pass
• [ ] Conflicts are resolved
• [ ] Using merge commit (not squash)
• [ ] Target branch is correct

After Merging PR

• [ ] Feature branch is deleted
• [ ] Jira tickets are updated
• [ ] Documentation is updated if needed
• [ ] Team is notified if needed

Tools and Automation

Git Aliases

Add these to your .gitconfig for faster workflow:

[alias]
    # View commits with ticket numbers
    tickets = log --oneline --all --grep="MSP2-"

    # Create feature branch
    feature = "!f() { git checkout -b feature/MSP2-$1-$2 dev; }; f"

    # Commit with ticket format
    feat = "!f() { git commit -m \"feat(MSP2-$1): $2\"; }; f"
    fix = "!f() { git commit -m \"fix(MSP2-$1): $2\"; }; f"

    # View graph
    graph = log --graph --oneline --all --decorate

    # List branches with last commit
    branches = branch -vv

Usage:

# Create feature branch
git feature 123 user-auth

# Commit with format
git feat 123 "Add authentication module"
git fix 124 "Resolve login error"

# View ticket history
git tickets

Pre-commit Hook

Create .git/hooks/pre-commit to validate commit messages:

#!/bin/bash
# Validate commit message format

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

# Check for ticket reference
if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|refactor|test|chore|perf|style)\(MSP2-[0-9]+\):"; then
    echo "Error: Commit message must follow format: type(MSP2-XX): Description"
    echo "Example: feat(MSP2-123): Add user authentication"
    exit 1
fi

exit 0

Troubleshooting

Problem: Mixed commits in dev branch

Solution: Use interactive rebase to reorganize

git checkout dev
git rebase -i HEAD~10  # Last 10 commits

# In editor, reorder commits by ticket
# Use 'squash' to combine commits for same ticket if needed

Problem: Forgot to reference ticket in commit

Solution: Amend the commit message

# If it's the last commit
git commit --amend -m "feat(MSP2-123): Correct message"

# If it's an older commit
git rebase -i HEAD~5  # Go back 5 commits
# Mark commit as 'reword' in editor
# Update message when prompted

Problem: Need to split a large commit

Solution: Use interactive rebase with edit

git rebase -i HEAD~3
# Mark commit as 'edit'

# Reset the commit but keep changes
git reset HEAD^

# Stage and commit changes separately
git add file1.js
git commit -m "feat(MSP2-123): Part 1"

git add file2.js
git commit -m "feat(MSP2-124): Part 2"

git rebase --continue

Problem: Accidentally squashed commits

Solution: Use reflog to recover

# Find the commit before squash
git reflog

# Reset to that commit
git reset --hard HEAD@{5}  # Adjust number as needed

Additional Resources

• Conventional Commits
• Git Best Practices
• Jira Git Integration
• Semantic Versioning

---

Document Version: 1.0 Last Updated: 2026-02-18 Maintained By: Development Team