The Git Workflow for Contributors

🔄 Recall Bridge: In the previous lesson, you learned to navigate unfamiliar codebases with AI — understanding architecture, tracing data flows, and finding where your change goes. Now let’s make sure your Git workflow doesn’t derail your contribution.

Git is the plumbing of open source. Every contribution flows through the same pipeline: fork → branch → commit → push → PR. Getting this workflow right means your contribution gets reviewed. Getting it wrong means your PR gets closed with a polite “please rebase and resubmit.”

The Complete Contribution Workflow

Step 1: Fork and Clone

# Fork the repository on GitHub (click the Fork button)
# Then clone YOUR fork (not the original)
git clone https://github.com/YOUR-USERNAME/project-name.git
cd project-name

# Add the original repository as "upstream"
git remote add upstream https://github.com/ORIGINAL-OWNER/project-name.git

Why fork? You can’t push directly to someone else’s repository. Your fork is your copy where you can make changes freely.

Step 2: Create a Feature Branch

# Always start from an up-to-date main
git checkout main
git pull upstream main

# Create a descriptive branch
git checkout -b fix/issue-42-date-parsing

Branch naming conventions:

Step 3: Make Your Changes

Work on your feature branch. Commit frequently with meaningful messages.

AI prompt for commit messages:

I made the following changes: [PASTE YOUR DIFF OR DESCRIBE CHANGES]. Write a commit message following this project’s convention: [CONVENTIONAL COMMITS / DESCRIPTIVE / etc.]. Include: (1) A clear subject line under 72 characters, (2) A body explaining what and why (not how — the code shows how), (3) Reference to the issue number if applicable.

Step 4: Keep Your Branch Updated

If the upstream project has new commits while you work:

# Fetch upstream changes
git fetch upstream

# Rebase your branch on top of upstream main
git rebase upstream/main

AI prompt for rebase conflicts:

I’m rebasing my branch onto upstream/main and got a conflict in [FILE]. My change: [YOUR CODE]. Upstream change: [THEIR CODE]. Explain what each change does and show me how to resolve this conflict so both changes work correctly.

Step 5: Push and Create a PR

# Push your branch to YOUR fork
git push origin fix/issue-42-date-parsing

Then create a Pull Request on GitHub from your branch to the upstream’s main branch.

Writing Good Commit Messages

Structure:

type: brief description (under 72 chars)

Longer explanation of what changed and why. Reference the issue
this addresses.

Fixes #42

Common commit types:

✅ Quick Check: You committed 12 small commits while working on your fix: “wip”, “trying another approach”, “maybe this works”, “cleanup”, “actually fix the thing”, etc. Should you open a PR with all 12 commits? (Answer: No. Squash your commits into 1-3 meaningful commits before opening the PR. Use git rebase -i HEAD~12 to combine them. Maintainers want to see a clean history — one commit that clearly explains the change, not your entire thought process. AI can help: “I have these 12 commit messages. Help me squash them into 2-3 logical commits with good messages.”)

Handling Merge Conflicts

Conflicts happen when you and someone else changed the same lines. Don’t panic.

AI prompt for understanding conflicts:

I have a merge conflict in [FILE]. Here’s the conflict marker section:

<<<<<<< HEAD
[your changes]
=======
[upstream changes]
>>>>>>> upstream/main

Explain what each side is doing and suggest the correct resolution. Should I keep mine, keep theirs, or combine both?

Conflict resolution strategies:

Syncing Your Fork

Keep your fork’s main branch in sync with upstream:

git checkout main
git fetch upstream
git merge upstream/main
git push origin main

Do this before creating new feature branches to avoid starting from outdated code.

Key Takeaways

• Always work on feature branches, never on main — this keeps your fork clean, lets you sync with upstream independently, and allows multiple simultaneous contributions; name branches descriptively with type prefixes like fix/issue-42-date-parsing
• Commit messages should explain the what and why, not the how — a specific subject line under 72 characters plus a body explaining the reasoning helps maintainers review your change without reading every line of code, and referencing issue numbers (Fixes #42) auto-closes issues when merged
• When facing merge conflicts, understand both sides before resolving — AI can explain what each side of a conflict does and suggest a resolution that preserves both changes’ intent, but never blindly discard upstream changes that a maintainer merged for a reason

Up Next

In the next lesson, you’ll learn how to write pull requests that maintainers love — from structuring the description to handling review feedback professionally.