Branching & Contribution

Simple and practical branching strategy that matches how we actually work in projects.

Branch Naming Convention

Follow this pattern: yourname/type/feature-description

Examples:

# Feature branches
john/feature/user-authentication
sarah/feature/payment-integration

# Bug fixes
mike/fix/login-error
alice/fix/header-styling

# Refactoring
bob/refactor/api-client
mary/refactor/user-service

# Other types
alex/docs/setup-guide
lisa/chore/update-dependencies

Basic Workflow

1. Create and Switch to Branch

# Create new branch from main
git checkout main
git pull origin main
git checkout -b yourname/feature/user-dashboard

2. Work on Your Feature

# Make changes
git add .
git commit -m "Add user dashboard component"

# Push to GitHub
git push origin yourname/feature/user-dashboard

3. Create Pull Request

Go to GitHub
Click “Compare & pull request”
Use the PR template
Link to related issue: Closes #123
Request review

4. After PR is Merged

# Switch back to main and clean up
git checkout main
git pull origin main
git branch -d yourname/feature/user-dashboard

Working with Issues

Issue to Branch Flow:

Pick an issue from the project
Assign yourself to the issue
Create branch using issue description
Work on the feature
Create PR that closes the issue

Example:

Issue #45: “Add dark mode toggle”
Branch: yourname/feature/dark-mode-toggle
PR title: “Add dark mode toggle (Closes #45)“

Collaboration Tips

Before Starting Work:

# Always start from latest main
git checkout main
git pull origin main
git checkout -b yourname/feature/new-feature

Keep Branch Updated:

# If main has new changes while you work
git checkout main
git pull origin main
git checkout yourname/feature/new-feature
git merge main

Small, Focused Changes:

One feature per branch
Keep PRs small and reviewable
Don’t mix different types of changes

Conflict Resolution & Avoidance

Preventing Conflicts

Best practices to avoid conflicts:

Pull from main frequently (at least daily)
Keep branches short-lived (merge within 2-3 days)
Communicate with team about file changes
Use clear commit messages

# Daily routine to avoid conflicts
git checkout main
git pull origin main
git checkout yourname/feature/current-work
git merge main  # or git rebase main for cleaner history

When Conflicts Happen

Step-by-step conflict resolution:

Fetch latest changes:

git checkout main
git pull origin main
git checkout yourname/feature/conflicted-branch
git merge main

Git will show conflict markers:

// Example conflict in a file
<<<<<<< HEAD
const apiUrl = 'https://api.staging.example.com';
=======
const apiUrl = 'https://api.production.example.com';
>>>>>>> main

Resolve conflicts manually:

// Choose the correct version or combine both
const apiUrl = process.env.NODE_ENV === 'production'
  ? 'https://api.production.example.com'
  : 'https://api.staging.example.com';

Complete the merge:

git add .
git commit -m "Resolve merge conflict in api configuration"
git push origin yourname/feature/conflicted-branch

Common Conflict Scenarios

# When multiple people add dependencies
# Always accept both changes and remove duplicates manually
git checkout --theirs package.json
npm install  # or yarn install
git add package.json package-lock.json

# When editing same lines in a file
# 1. Look at both changes
# 2. Decide which is correct or combine them
# 3. Remove conflict markers (<<<, ===, >>>)
# 4. Test the changes work

# When file is renamed/moved in different branches
# 1. Choose the correct location
# 2. Make sure imports are updated
# 3. Delete the duplicate file if exists
git add .
git rm old-file-name.js  # if needed

If You’re Stuck

When conflicts seem overwhelming:

Reset and try again:

git merge --abort  # Cancel the merge
git checkout main
git pull origin main
# Start over with fresh approach

Ask for help:

Share your screen with a teammate
Use GitHub’s conflict resolution interface
Create a new branch and cherry-pick specific commits

Use VS Code merge tools:

Install Git Graph extension
Use built-in merge conflict resolver
Visual diff makes conflicts easier to understand

Common Scenarios

Working on Same Feature:

If multiple people work on one big feature:

Create feature branch: feature/payment-system
Everyone branches from it: john/feature/payment-ui, sarah/feature/payment-api
Merge individual branches to feature branch
Merge feature branch to main when complete

Hotfix:

For urgent production fixes:

# Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b yourname/hotfix/critical-security-fix

# After fix, create PR to main immediately