0%
Tutorial 6 of 10
60% complete

Collaborating with GitHub

Master pull requests, issues, and discussions to collaborate effectively with other developers.

Collaborating with GitHub

GitHub has revolutionized collaboration in software development. This tutorial will teach you how to use GitHub’s collaboration tools (pull requests, issues, discussions, and more) to work effectively as a team.

Collaboration Overview

ForkClonePushPull RequestReviewMergePullDéveloppeur ADépôt ForkDépôt Local ABranche FeatureDépôt OriginalDéveloppeur BMaintainerDépôt Local B

Issues: Managing Tasks and Bugs

What Is an Issue?

An issue is a ticket used to:

  • Report bugs
  • Suggest features
  • Ask questions
  • Organize tasks

Creating an Issue

# Bug issue template
**Bug description**
A clear and concise description of the problem.

**Steps to reproduce**
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See the error

**Expected behavior**
A description of what should happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
- OS: [e.g. iOS]
- Browser: [e.g. chrome, safari]
- Version: [e.g. 22]

Managing Issues

# With GitHub CLI
gh issue create --title "Bug dans le login" --body "Description détaillée"
gh issue list
gh issue view 123
gh issue close 123

# Assign an issue
gh issue edit 123 --add-assignee username

# Add labels
gh issue edit 123 --add-label bug,priority-high

Labels and Organization

Default labels:

  • bug: Something isn’t working
  • enhancement: New feature or request
  • documentation: Documentation improvements
  • good first issue: Good for new contributors
  • help wanted: Extra help is wanted

Custom labels:

priority-high (red)
priority-medium (orange)
priority-low (green)
frontend (blue)
backend (purple)

Pull Requests: Proposing Changes

Pull Request Workflow

# 1. Fork the repository (via the GitHub interface)
# 2. Clone your fork
git clone https://github.com/VOTRE-USERNAME/projet.git
cd projet

# 3. Create a branch
git checkout -b feature/nouvelle-fonctionnalite

# 4. Develop and commit
echo "nouveau code" > feature.js
git add feature.js
git commit -m "feat: add new feature"

# 5. Push the branch
git push origin feature/nouvelle-fonctionnalite

# 6. Create the Pull Request via the GitHub interface

Anatomy of a Pull Request

# Pull Request Template

## Description
Summary of the changes and motivation.

## Type of change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would break existing functionality)
- [ ] Documentation

## How has this been tested?
Description of the tests performed.

## Checklist:
- [ ] My code follows the project's guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective
- [ ] New and existing tests pass locally

GitHub CLI Commands for PRs

# Create a PR
gh pr create --title "Add new feature" --body "Description détaillée"

# List PRs
gh pr list

# View a PR
gh pr view 123

# Check out a PR for testing
gh pr checkout 123

# Merge a PR
gh pr merge 123 --merge  # or --squash or --rebase

# Close a PR
gh pr close 123

Code Review

Review Process

  1. Read the code: Understand the changes
  2. Test locally: Verify that it works
  3. Constructive feedback: Useful comments
  4. Approval or change request

Types of Comments

# General comment
This approach is interesting, but have you considered using X instead of Y?

# Code suggestion
```suggestion
function calculateTotal(items) {
    return items.reduce((sum, item) => sum + item.price, 0);
}

Question

Why did you choose this method over the native API?

Nitpick (minor detail)

nit: Missing space after the comma


### Review Best Practices

**For the reviewer:**
- Be constructive and respectful
- Explain the "why" behind your suggestions
- Approve good PRs quickly
- Test significant changes

**For the author:**
- Respond to comments
- Implement relevant suggestions
- Ask for clarification if needed
- Thank reviewers for their feedback

## Forks and Contributions

### Forking a Project

```bash
# 1. Fork via the GitHub interface
# 2. Clone your fork
git clone https://github.com/VOTRE-USERNAME/projet-fork.git
cd projet-fork

# 3. Add the original repository as a remote
git remote add upstream https://github.com/AUTEUR-ORIGINAL/projet.git

# 4. Check the remotes
git remote -v

Syncing with Upstream

# Fetch changes from upstream
git fetch upstream

# Merge the changes into your main branch
git checkout main
git merge upstream/main

# Push to your fork
git push origin main

Contribution Workflow

# 1. Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main

# 2. Create a branch for your contribution
git checkout -b fix/bug-description

# 3. Develop
# ... changes ...

# 4. Commit
git add .
git commit -m "fix: resolve issue with user authentication"

# 5. Push to your fork
git push origin fix/bug-description

# 6. Create a Pull Request to upstream

GitHub Discussions

Types of Discussions

  • Q&A: Questions and answers
  • Ideas: Idea proposals
  • General: General discussions
  • Show and tell: Share your work

Creating a Discussion

# Example "Ideas" discussion
**Title:** Add a dark mode to the application

**Description:**
I propose adding a dark mode to improve the user experience,
especially for nighttime use.

**Benefits:**
- Reduced eye strain
- Battery savings on OLED screens
- Modern design trend

**Questions:**
- Which color palette should we use?
- Should there be an automatic toggle based on the time of day?
- How do we handle compatibility with existing themes?

Project Management with GitHub

GitHub Projects

# Organizing a project
Typical columns:
- Backlog
- To Do
- In Progress
- In Review
- Done

# Automation
- Automatically move cards based on events
- Link issues and PRs to cards
- Filter by assignee, label, milestone

Milestones

# Organize issues by version/sprint
Milestone: Version 2.0
- Issue #45: Add OAuth authentication
- Issue #46: Improve performance
- Issue #47: Fix the navigation bug

Due date: 2024-03-15
Progress: 2/3 issues closed (67%)

Notifications and Mentions

Notification System

# Types of notifications
- Mentions (@username)
- Assignments
- Review requests
- Comments on your PRs/issues
- Activity on watched repositories

# Managing notifications
Settings > Notifications
- Email notifications
- Web notifications
- Mobile notifications

Mentions and Teams

# Mention a user
@username can you take a look at this PR?

# Mention a team
@org/frontend-team this PR affects the user interface

# Mention in a commit
git commit -m "fix: resolve login issue

Fixes #123
cc @maintainer-team"

Security and Permissions

Access Levels

  • Read: Clone and read
  • Triage: Manage issues and PRs
  • Write: Push and merge
  • Maintain: Manage the repository without destructive access
  • Admin: Full access

Branch Protection

# Protection rules for main
- Require pull request reviews before merging
- Require status checks to pass before merging
- Require branches to be up to date before merging
- Require conversation resolution before merging
- Restrict pushes that create files larger than 100MB

Hands-On Exercises

Exercise 1: Your First Contribution

# 1. Fork a simple open source project
# 2. Clone your fork
git clone https://github.com/VOTRE-USERNAME/projet-fork.git

# 3. Create a branch
git checkout -b docs/improve-readme

# 4. Improve the documentation
echo "## Installation\n\n\`\`\`bash\nnpm install\n\`\`\`" >> README.md

# 5. Commit and push
git add README.md
git commit -m "docs: improve installation instructions"
git push origin docs/improve-readme

# 6. Create a Pull Request

Exercise 2: Issue Management

# 1. Create several issues in your repository
gh issue create --title "Bug: Login ne fonctionne pas" --label bug
gh issue create --title "Feature: Ajouter mode sombre" --label enhancement
gh issue create --title "Docs: Améliorer le README" --label documentation

# 2. Assign and organize
gh issue edit 1 --add-assignee VOTRE-USERNAME
gh issue edit 2 --add-label "good first issue"

# 3. Link a PR to an issue
git checkout -b fix/login-bug
# ... development ...
git commit -m "fix: resolve login authentication issue

Fixes #1"

Exercise 3: Code Review

# 1. Create a PR with code to improve
echo "function add(a,b){return a+b}" > math.js
git add math.js
git commit -m "add math function"
git push origin feature/math

# 2. Create the PR and request a review
gh pr create --title "Add math utilities" --reviewer ami-reviewer

# 3. Respond to comments and improve
echo "function add(a, b) {
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new Error('Both arguments must be numbers');
  }
  return a + b;
}" > math.js

git add math.js
git commit -m "improve: add input validation to math function"
git push origin feature/math

Tools and Integrations

GitHub Desktop

A graphical interface for:

  • Viewing changes
  • Creating commits
  • Managing branches
  • Syncing with GitHub

VS Code + GitHub

Useful extensions:

  • GitHub Pull Requests and Issues
  • GitLens
  • GitHub Copilot

CI/CD Integrations

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '16'
      - run: npm install
      - run: npm test

Collaborative Best Practices

Communication

  1. Be clear in your descriptions
  2. Use templates for issues and PRs
  3. Respond quickly to reviews
  4. Document your important decisions

Organization

  1. Use consistent labels
  2. Organize with milestones
  3. Assign responsibilities
  4. Close resolved issues

Code

  1. Atomic, descriptive commits
  2. Short, focused branches
  3. Tests for new features
  4. Up-to-date documentation

Collaborative Troubleshooting

Merge Conflicts in a PR

# 1. Sync with the main branch
git fetch origin
git checkout feature-branch
git merge origin/main

# 2. Resolve the conflicts
# ... manual editing ...

# 3. Commit the resolution
git add .
git commit -m "resolve merge conflicts"
git push origin feature-branch

PR Blocked by Checks

# Check the status checks
gh pr checks

# Re-run the checks if necessary
gh pr ready --undo  # mark as draft
gh pr ready         # mark as ready

Additional Resources

GitHub Documentation

Third-Party Tools

  • Conventional Commits: A standard for commit messages
  • Semantic Release: Version automation
  • All Contributors: Recognizing contributors

Conclusion

Collaboration on GitHub goes well beyond simply sharing code. It is a complete ecosystem that facilitates communication, organization, and software development quality. Mastering these tools will make you more effective in your collaborative projects.

In the next tutorial, we will dive deeper into conflict resolution, a crucial aspect of team collaboration.

Estimated reading time: 25 minutes
Level: Intermediate
Previous step: Introduction to GitHub
Next step: Resolving Conflicts

← Previous Introduction to GitHub Next → Resolving Conflicts
← Previous Introduction to GitHub Next → Resolving Conflicts