Git Workflow Guide for Contributors

Git Workflow for Contributors

Many contributors, especially newcomers, struggle with the fork-and-PR workflow. A clear git workflow section prevents common mistakes.

Fork and Clone

# 1. Fork the repository on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/project.git
cd project

# 3. Add the upstream remote
git remote add upstream https://github.com/ORIGINAL_ORG/project.git

Creating a Branch

# Always branch from an up-to-date main
git checkout main
git pull upstream main
git checkout -b feature/my-new-feature

Keeping Your Fork in Sync

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

Making Commits

git add src/components/NewFeature.tsx
git add src/tests/NewFeature.test.tsx
git commit -m "feat: add new feature component"

Before Submitting a PR

# Rebase on latest main to avoid conflicts
git checkout main
git pull upstream main
git checkout feature/my-new-feature
git rebase main

# Run all checks
npm run lint
npm test
npm run build

Resolving Conflicts

# During rebase, if conflicts occur:
# 1. Fix the conflicting files
# 2. Stage the resolved files
git add <resolved-file>
# 3. Continue the rebase
git rebase --continue

Pushing Changes

# First push
git push origin feature/my-new-feature

# After rebase (force push to your fork only)
git push --force-with-lease origin feature/my-new-feature

Common Mistakes

• Making changes on main instead of a feature branch
• Forgetting to sync with upstream before starting work
• Using git push --force instead of --force-with-lease
• Committing generated files or dependencies