Collaborative Git Workflows

Module 1 - GIST 604B

Professional Collaboration Using GitHub Web Interface

No command line required—learn through point-and-click

The Collaborative Git Workflow

🔄 Five Key Steps:

1. Branch
Create isolated workspace
→
2. Commit
Save your changes
→
3. Pull Request
Propose changes
→
4. Review
Discuss & improve
→
5. Merge
Integrate code
💡 Key Principle: Isolated development → Quality review → Safe integration

2. COMMIT What is a Commit?

A commit is a snapshot of your project at a point in time

  • Saves your changes
    Records what you've done to the repository
  • Has a unique ID
    Every commit gets a unique hash (like a3f82b1)
  • Includes a message
    Describes what changed and why
  • Points to parent
    Creates history chain back to first commit
  • Permanent record
    Can't be changed once created (only added to)
💡 Key Concept: Think of commits as save points in a video game—you can always go back to any commit to see what the project looked like at that moment.

1. BRANCH What is a Branch?

A branch is a pointer to a commit

  • Points to a specific commit
    The "tip" of the branch
  • Grows by adding commits
    Each new commit moves the tip forward
  • Diverges from main
    Your changes isolated from stable code
  • Linear history
    Each commit points back to its parent, all the way to the first commit
Git branch diagram showing main and feature branches diverging from common base
💡 Key Insight: Branches let you work independently while main stays stable. When ready, merge brings your changes back together.

1. BRANCH Branch Naming Conventions

feature/add-postgis-layer
New functionality
fix/coordinate-precision-bug
Bug fixes
docs/update-installation
Documentation updates
🖱️ Creating Branches on GitHub:
1. Click the branch dropdown (shows "main")
2. Type your new branch name: feature/add-spatial-query
3. Click "Create branch: feature/add-spatial-query"
4. You're now on your new branch—ready to edit files!

2. COMMIT Making Good Commits

A commit is a snapshot of your work

Good Commit Messages:

✅ Add support for GeoJSON export
Clear, specific, action-oriented
✅ Fix coordinate precision bug in buffer calculation
Explains what and why

Poor Commit Messages:

❌ Update code
Too vague
❌ Fix bug
Which bug?
❌ WIP
Not descriptive
💡 Commit Best Practices:
• Make atomic commits (one logical change)
• Commit often (small, focused changes)
• Write present-tense messages ("Add" not "Added")
• Think: "This commit will..." [your message]

3. PULL REQUEST What is a Pull Request?

A pull request (PR) is a proposal to merge your branch into another branch

  • Proposes changes
    "I've finished my work, please review and merge it"
  • Opens discussion
    Team can review, comment, and suggest improvements
  • Shows differences
    GitHub displays exactly what changed between branches
  • Tracks conversation
    All feedback, questions, and decisions in one place
  • Gateway to merge
    After approval, changes can be merged into main branch
💡 Think of it like: You wrote a paper and are asking your professor to review it before including it in the final publication. The PR is your submission + their feedback.

3. PULL REQUEST Anatomy of a Good Pull Request

✅ Clear Title:
"Add support for GeoJSON export in QGIS plugin"
Description Template: 
## Description
Adds CSV export functionality to spatial analysis results

## Motivation
Users requested ability to export for Excel (#42)

## Changes
- Added export_to_csv() function in utils.py
- Updated UI with "Export" button
- Added tests for CSV generation
- Updated README with export documentation

## Testing
- Manual testing with sample datasets
- All existing tests pass
- New tests added for CSV export

Good PRs get merged; poor PRs get ignored

3. PULL REQUEST Pull Request Best Practices

  • 📝 Clear Title: Descriptive and specific
    Good: "Add GeoJSON export" | Bad: "Update code"
  • 📋 Detailed Description: What, why, how, testing
    Help reviewers understand your changes
  • 🎯 Small, Focused Changes: One PR = one feature
    Easier to review = faster to merge
  • ✨ Clean Commit History: Logical, atomic commits
    Tell a story of development
  • 🖼️ Screenshots: If UI changes
    Visual confirmation helps reviewers

4. REVIEW Why Review My Pull Request?

Even solo projects benefit from the review process

For Solo Projects:

  • Catch mistakes
    Fresh eyes spot bugs you missed
  • Improve code quality
    Get suggestions for better approaches
  • Learn best practices
    Reviewers share their expertise
  • Document decisions
    PR discussion explains "why"

For Team Projects:

  • Keep everyone aligned
    Team knows where project is going
  • Maintain consistency
    Naming conventions, code style
  • Share knowledge
    Everyone learns how the code works
  • Prevent conflicts
    Catch issues before they're merged
💡 Key Insight: Code review might seem like overkill for solo work, but it's a professional habit that improves code quality and catches mistakes. For teams, it's essential for coordination, consistency, and shared understanding.

4. REVIEW Code Review Best Practices

As a Reviewer:

  • ✅ Be respectful and constructive
  • ✅ Focus on code, not person
  • ✅ Explain "why" when requesting changes
  • ✅ Acknowledge good work
  • ✅ Suggest alternatives, don't just criticize
  • ✅ Review promptly (contributors are waiting)
✅ Good Review Comment:
"Nice work on the spatial indexing! One suggestion: Consider using R-tree instead of quad-tree here for better performance with dense point clouds. See: [link to documentation]"
❌ Bad Review Comment:
"This is wrong. Change it."

4. REVIEW Receiving Code Review

As a Contributor:

  • ✅ Don't take feedback personally
  • ✅ Ask questions if unclear
  • ✅ Discuss trade-offs professionally
  • ✅ Iterate based on feedback
  • ✅ Say thank you for thorough reviews
💡 Remember: Code review is collaborative teaching, not criticism.
Every reviewer was once a beginner receiving feedback.

Professional developers welcome constructive feedback

5. MERGE What is Merging?

Merging integrates changes from one branch into another

  • Combines work
    Brings your feature branch changes into main
  • Preserves history
    Both branches' commits remain in the history
  • Creates merge commit
    Special commit that joins two branches together
Git merge diagram showing branches merging back together

Two Possible Outcomes:

✅ Clean Merge (No Conflicts)
  • Git automatically combines changes
  • No overlapping edits
  • Different files modified
  • Different parts of same file
  • Result: Instant merge ✨
⚠️ Merge Conflict
  • Both branches changed same lines
  • Git can't automatically decide
  • Conflicting edits to code
  • Human decision required
  • Result: Manual resolution needed 🛠️
💡 Why conflicts happen: Two people edited the same lines in different ways. Git doesn't know which version to keep, so it asks you to decide. This is completely normal!

5. MERGE Understanding Merge Conflicts

🤔 What Are Merge Conflicts?

  • Two people edited the same lines of code
  • Git can't automatically merge
  • You must manually decide which changes to keep
⚠️ Common Scenario:
You're working on feature branch → Meanwhile, main branch updated → Your branch now conflicts with main

💡 The Good News: Conflicts are normal! Resolution is a learned skill.

5. MERGE Resolving Merge Conflicts (Web UI)

⚠️ When Conflicts Occur: GitHub shows "This branch has conflicts that must be resolved"
1. Click "Resolve conflicts" button on the Pull Request page
GitHub opens web-based conflict editor
2. GitHub shows conflict markers: 
<<<<<<< your-feature-branch (your changes)
result = calculate_distance(point1, point2)
=======
result = compute_spatial_distance(point1, point2)
>>>>>>> main (their changes)
3. Edit in Web Editor:
• Delete conflict markers (<<<<<<<, =======, >>>>>>>)
• Keep your changes, their changes, or blend both
• Result: result = compute_spatial_distance(point1, point2)
4. Mark as resolved: Click "Mark as resolved" button
5. Commit merge: Click "Commit merge" button
✅ Conflict resolved! PR can now be merged

5. MERGE Preventing Merge Conflicts

  • 🔄 Sync with main frequently
    Don't let your branch drift too far
  • ⚡ Keep branches short-lived
    Merge quickly, don't leave branches open for weeks
  • 💬 Communicate with team
    "I'm working on the auth module"
  • 🎯 Small, focused changes
    Smaller PRs = fewer conflicts
  • 👥 Divide work clearly
    Different developers, different files when possible

Prevention is easier than resolution!

Assignment: M1A4

Practice Collaborative Workflows

What You'll Do (All in GitHub Web UI):

  • Work with a partner on a shared repository
  • Create feature branches for your changes
  • Make meaningful GIS-related edits using web editor
  • Create pull requests with clear descriptions
  • Review your partner's pull requests with constructive feedback
  • Experience and resolve merge conflicts together

Learning Goals (Real Collaboration!):

  • 🤝 Collaborate effectively - coordinate changes with a teammate
  • 🌿 Branch management - create and work in isolated branches
  • 💬 Communication - write clear PRs and give helpful feedback
  • 🔀 Merging experience - integrate changes and handle conflicts
  • 🛠️ Conflict resolution - resolve overlapping edits together

🎯 Focus: Learn collaboration, merging, and conflict resolution through hands-on practice!

Essential Resources

GitHub Web UI Documentation: Optional Tools (Advanced):
  • GitHub Desktop (GUI app)
  • VSCode Git integration
  • Command line (not needed for this course)
Practice: Real Examples:

💡 Focus on GitHub's web interface first—it's all you need to contribute!

Key Takeaways

  • ✅ Collaborative workflows enable quality code at scale
  • ✅ Branches isolate work; PRs propose changes
  • ✅ GitHub web UI makes these workflows accessible
  • ✅ Good PRs are clear, focused, and well-tested
  • ✅ Code review is collaborative teaching
  • ✅ Merge conflicts are normal—web UI makes resolution easier
  • ✅ This is how you contribute to open source

These are job-ready skills

By completing M1A4 (100% web UI), you'll know professional Git workflows
used by developers worldwide—no command line needed!

Ready to collaborate? Let's practice in M1A4!