GitHub Workflow¶

Progress: Module 4 of 4 - Lesson 1 of 3

Master Git branching strategies, pull request workflows, and code organization patterns for effective team collaboration.

Prerequisites¶

Before diving into GitHub workflow, ensure you have:

Git installed and configured on your machine
Access to your team's GitHub repository
Completed previous modules (or have relevant Git knowledge)
Familiarity with basic Git commands (commit, push, pull)

Core Concepts¶

Branching Strategy: GitHub Flow¶

GitHub Flow is a lightweight branching model ideal for continuous deployment:

Main Branch (always production-ready)
├── Feature Branch 1 → Pull Request → Code Review → Merge
├── Feature Branch 2 → Pull Request → Code Review → Merge
└── Feature Branch 3 → Pull Request → Code Review → Merge

Key Principles¶

Main Branch is Sacred
Must always be deployable
All code is tested before merging
Represents production state
Feature Branches
One feature per branch
Descriptive names
Created from main
Short-lived (days, not weeks)
Pull Request as Discussion
PRs are for code review, not just merging
Include context and rationale
Respond to feedback promptly

Team Collaboration Best Practices¶

Branch Naming Conventions¶

Follow your team's convention (examples):

feature/user-authentication
feature/dashboard-redesign
bugfix/login-redirect-issue
docs/api-documentation
chore/dependency-updates

Best Practices: - Use lowercase letters and hyphens - Be descriptive but concise - Include issue/ticket number if applicable - Avoid generic names like "fix" or "update"

Commit Message Standards¶

Write clear, meaningful commit messages:

Good:
- "Add email verification to signup flow"
- "Fix race condition in cache invalidation"
- "Update authentication error messages"

Avoid:
- "Fixed stuff"
- "WIP"
- "asdf"
- "Update"

Commit Message Format:

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

<body>

<footer>

Types: feat, fix, docs, style, refactor, test, chore

Example:

feat(auth): add two-factor authentication

Implement TOTP-based 2FA for user accounts.
Users can enable 2FA in security settings.

Closes #345

Pull Request Workflow¶

Step 1: Create Feature Branch¶

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

Step 2: Make Changes and Commit¶

git add .
git commit -m "feat(scope): description"
git push origin feature/your-feature-name

Step 3: Create Pull Request¶

Push to GitHub
Open pull request with context
Request reviewers
Link related issues

Step 4: Address Review Comments¶

# Make changes locally
git add .
git commit -m "Address review feedback"
git push origin feature/your-feature-name
# Comments automatically reflect in PR

Step 5: Merge and Cleanup¶

# After approval, merge via GitHub UI
git checkout main
git pull origin main
git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name

Code Organization Patterns¶

Organize by Feature¶

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── services/
│   │   └── types/
│   ├── dashboard/
│   │   ├── components/
│   │   ├── services/
│   │   └── types/
│   └── settings/
│       ├── components/
│       ├── services/
│       └── types/
└── shared/
    ├── components/
    ├── hooks/
    ├── services/
    └── types/

Organize by Layer¶

src/
├── components/     # UI components
├── services/       # Business logic
├── repositories/   # Data access
├── models/         # Data types
└── utils/          # Helper functions

Keeping Branches Up to Date¶

When working on long-lived branches:

# Rebase approach (preferred for clean history)
git fetch origin
git rebase origin/main

# Merge approach (safer for shared branches)
git fetch origin
git merge origin/main

AI Prompts for Git Commands¶

Understanding Git History¶

Explain Git Commit History

I'm looking at our repository history and confused.

Output from `git log --oneline --graph`:
[paste the output]

Help me understand:
1. What do the branch lines mean?
2. What is HEAD pointing to?
3. How do I see changes in a specific commit?
4. How do I compare two branches?

Undoing Commits Safely¶

I Need to Undo a Commit

I committed something wrong and need to undo it.

Situation:
- Commit I want to undo: [commit hash or description]
- Has it been pushed to GitHub? [yes/no]
- Are other people working on this branch? [yes/no]

Output from `git log -3`:
[paste recent commits]

Guide me step-by-step to:
1. Safely undo the commit
2. Keep/discard the changes
3. Fix the branch history
4. Update remote if needed

Creating Feature Branches¶

Help Me Create Feature Branch

I'm starting work on [feature description] and need a new branch.

Current situation:
- Currently on branch: [current branch from `git branch`]
- Want to create branch: [desired branch name]
- Should branch from: main

Guide me through:
1. Creating the branch with proper naming
2. Switching to it
3. Making first commit
4. Pushing to GitHub
5. Creating a pull request

Syncing with Main Branch¶

Keep My Branch Updated

My feature branch is outdated compared to main.

My branch: [feature-branch-name]

Output from `git status`:
[paste status]

Help me:
1. Get latest changes from main
2. Merge or rebase? Which is better for this case?
3. Handle any conflicts that arise
4. Push updated branch to GitHub

Handling Merge Conflicts¶

Help Me Resolve Merge Conflicts

I have merge conflicts after trying to merge/rebase.

Output from `git status`:
[paste status showing conflicts]

Conflicted files:
[list the files with conflicts]

Walk me through:
1. Understanding the conflict markers (<<<<<<, ======, >>>>>>)
2. How to decide which changes to keep
3. Testing after resolution
4. Completing the merge/rebase
5. Best practices to avoid conflicts in the future

Squashing Commits¶

Clean Up Commit History

I have multiple messy commits and want to clean them up before PR.

Output from `git log --oneline -10`:
[paste recent commits]

I want to:
- Squash commits [commit range or description]
- Keep commits [which ones to preserve]
- Final commit message should be: [desired message]

Show me how to:
1. Use interactive rebase to squash commits
2. Write a clear combined commit message
3. Force push safely to my branch
4. When NOT to squash commits

Moving Commits Between Branches¶

I Committed to Wrong Branch

I accidentally committed to the wrong branch.

Situation:
- Currently on branch: [wrong branch]
- Commit hash: [hash from `git log -1`]
- Should be on branch: [correct branch name]
- Does correct branch exist? [yes/no]

Output from `git log -3`:
[paste recent commits]

Help me:
1. Move the commit to the correct branch
2. Remove it from the wrong branch
3. Ensure I don't lose any work
4. Update GitHub if already pushed

Cherry-Picking Commits¶

Apply Specific Commit from Another Branch

I need a specific commit from another branch without merging everything.

Scenario:
- Current branch: [my-branch]
- Commit I need is in: [other-branch]
- Commit hash or description: [commit details]

Output from `git log other-branch --oneline -5`:
[paste commits from other branch]

Show me how to:
1. Cherry-pick the specific commit
2. Handle conflicts if they occur
3. Verify the changes applied correctly
4. When to use cherry-pick vs merge

Common Workflows¶

Fixing a Mistake in Your PR¶

Scenario: You committed something you shouldn't have

# Option 1: Amend the last commit
git add .
git commit --amend --no-edit
git push origin feature/your-branch --force-with-lease

# Option 2: Revert a commit
git revert <commit-hash>
git push origin feature/your-branch

# Option 3: Reset to a previous state
git reset --soft HEAD~1  # Keep changes
git reset --hard HEAD~1  # Discard changes

Syncing with Main¶

Scenario: Main has moved ahead and you need the latest changes

# Method 1: Rebase (cleaner history)
git fetch origin
git rebase origin/main
git push origin feature/your-branch --force-with-lease

# Method 2: Merge (safer)
git fetch origin
git merge origin/main
git push origin feature/your-branch

Handling Merge Conflicts¶

Scenario: Your branch conflicts with main

# Start the rebase (or merge)
git rebase origin/main

# Git will pause at conflicts. Edit files to resolve.
# After editing:
git add <resolved-files>
git rebase --continue

# Or abort if needed:
git rebase --abort

Checklist Before Creating a PR¶

Branch is up to date with main
Code passes all tests locally
Commit messages are clear and descriptive
No debugging code or console logs left
Code follows team style guide
Changes are focused on one feature/fix
PR description explains the "why"
Related issues are linked
Tests are included for new features

FAQ¶

Q: How many commits should be in a PR? A: Depends on context. 1-5 is typical. More than that might indicate the change is too large.

Q: Should I force push? A: Use --force-with-lease only on your own branches. Never force push to main or shared branches.

Q: What if my PR is too large? A: Break it into smaller, logical PRs. Each should be reviewable in 15-30 minutes.

Q: How long should a branch live? A: Ideally 1-3 days. Longer-lived branches accumulate merge conflicts.

What's Next¶

Once you've mastered GitHub workflow, move on to:

Code Reviews →

Learn how to review code effectively and provide constructive feedback that improves code quality.

Help & Resources¶

Stuck with Git? - Check Git documentation - Review your team's Git guidelines - Ask for help from teammates

Common Issues? - Merge conflicts: Review conflict markers carefully - Lost commits: Check git reflog - Wrong branch: Stash changes and switch (git stash, git checkout)

Want to Learn More? - Advanced Git: explore git bisect, git worktree - CI/CD integration with GitHub - Automated testing in pull requests

Next Lesson: Code Reviews →