Git & GitHub

Team Collaboration Strategies

13 min Lesson 34 of 35

Team Collaboration Strategies

In this lesson, we'll explore strategies for effective team collaboration using Git and GitHub. These practices ensure smooth coordination, code quality, and project success when working with multiple developers.

Setting Up Team Repositories

Proper repository setup is crucial for team collaboration:

Initial Repository Setup Checklist:

✓ Create meaningful repository name
✓ Add comprehensive README.md
✓ Include LICENSE file
✓ Set up .gitignore for your tech stack
✓ Add CONTRIBUTING.md guidelines
✓ Create CODE_OF_CONDUCT.md
✓ Set up issue templates
✓ Create pull request template
✓ Configure branch protection rules
✓ Set up GitHub Actions for CI/CD

Essential repository files:

# README.md - Project overview
- Project description
- Installation instructions
- Usage examples
- Documentation links
- Contributing guidelines link
- License information

# CONTRIBUTING.md - Contribution guidelines
- How to set up development environment
- Coding standards and conventions
- Branch naming conventions
- Commit message guidelines
- Pull request process
- Code review expectations

# .github/PULL_REQUEST_TEMPLATE.md
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tests pass locally
- [ ] Added new tests
- [ ] Updated documentation

## Related Issues
Closes #123

Pro Tip: Create a repository template with all these files pre-configured, so new projects can start with best practices built in.

Branch Protection Rules

Branch protection prevents direct pushes to important branches and enforces quality standards:

# Configuring Branch Protection
1. Go to Settings > Branches
2. Add branch protection rule
3. Branch name pattern: main (or master)
4. Configure protection settings

Recommended Protection Settings:

✓ Require pull request before merging
  - Require approvals: 1-2 reviewers
  - Dismiss stale approvals on new commits
  - Require review from Code Owners

✓ Require status checks to pass
  - Require branches to be up to date
  - Add required checks (tests, linting, build)

✓ Require conversation resolution
  - All comments must be resolved

✓ Require signed commits (optional)
  - Ensures commit authenticity

✓ Require linear history (optional)
  - Prevents merge commits, enforces rebase

✓ Include administrators
  - Even admins must follow these rules

✗ Allow force pushes: NEVER
✗ Allow deletions: NEVER

Critical: Always protect your main/production branches. A single force push can destroy team history and cause major disruptions.

CODEOWNERS File

CODEOWNERS automatically assigns reviewers based on file paths:

# .github/CODEOWNERS

# Global owners (fallback for everything)
*       @org/senior-developers

# Frontend code
*.js    @org/frontend-team
*.jsx   @org/frontend-team
*.css   @org/frontend-team
/src/components/  @org/frontend-team @jane

# Backend code
*.py    @org/backend-team
*.java  @org/backend-team
/src/api/  @org/backend-team @john

# Database
*.sql   @org/database-team @bob
/migrations/  @org/database-team

# DevOps and CI/CD
*.yml   @org/devops-team
*.yaml  @org/devops-team
Dockerfile  @org/devops-team
/.github/workflows/  @org/devops-team @alice

# Documentation
*.md    @org/documentation-team
/docs/  @org/documentation-team

# Security-sensitive files
/config/secrets/  @org/security-team
*.key   @org/security-team

How CODEOWNERS works:

1. Developer creates PR touching src/components/Button.js
2. GitHub automatically requests review from @org/frontend-team
3. At least one frontend team member must approve
4. Once approved and checks pass, PR can be merged

Benefits:
✓ Automatic reviewer assignment
✓ Ensures relevant experts review changes
✓ Reduces bottlenecks (distributes reviews)
✓ Improves code quality
✓ Knowledge distribution across team

Important: CODEOWNERS works best with branch protection requiring code owner reviews. Enable "Require review from Code Owners" in branch protection settings.

Required Reviews

Establish clear code review requirements for your team:

Review Requirements by PR Type:

Small Changes (1-50 lines):
- 1 approval required
- Quick turnaround expected
- Examples: typo fixes, minor updates

Medium Changes (51-300 lines):
- 1-2 approvals required
- Detailed review needed
- Examples: new features, refactoring

Large Changes (301+ lines):
- 2+ approvals required
- Consider breaking into smaller PRs
- Examples: major features, architecture changes

Critical Changes:
- 2-3 approvals + security team review
- Extensive testing required
- Examples: authentication, payments, data migration

Review response time expectations:

Team Review SLA:

Priority 1 (Hotfix): 1-2 hours
Priority 2 (High): 24 hours
Priority 3 (Normal): 48 hours
Priority 4 (Low): 1 week

Reviewer responsibilities:
✓ Respond within SLA timeframe
✓ Provide constructive feedback
✓ Test changes if possible
✓ Check for security issues
✓ Verify documentation updates
✓ Approve or request changes clearly

Status Checks Configuration

Automated status checks ensure code quality before merging:

Essential Status Checks:

1. Automated Tests
   - Unit tests
   - Integration tests
   - End-to-end tests
   - Minimum coverage: 80%

2. Code Linting
   - ESLint (JavaScript/TypeScript)
   - Pylint (Python)
   - RuboCop (Ruby)
   - Enforce code style consistency

3. Security Scanning
   - Dependency vulnerability scanning
   - Code security analysis
   - Secret detection

4. Build Verification
   - Successful build required
   - No build warnings
   - Docker image builds (if applicable)

5. Performance Checks
   - Bundle size limits
   - Performance budget
   - Lighthouse scores (frontend)

Example GitHub Actions workflow for status checks:

name: Pull Request Checks

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Run linter
        run: npm run lint
      - name: Run tests
        run: npm test
      - name: Check coverage
        run: npm run coverage
      - name: Build
        run: npm run build

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run security scan
        run: npm audit
      - name: Check for secrets
        uses: trufflesecurity/trufflehog@main

Important: Status checks must be reliable. Flaky tests that randomly fail will frustrate the team and may be disabled, defeating their purpose.

Managing Access and Permissions

Properly configured permissions maintain security while enabling collaboration:

Repository Permission Levels:

Read:
- View code
- Clone repository
- Open issues
- Comment on issues/PRs
- Use for: External contributors, stakeholders

Triage:
- Read permissions +
- Manage issues and PRs
- Apply labels
- Close/reopen issues
- Use for: Community managers, project managers

Write:
- Triage permissions +
- Push to non-protected branches
- Create branches
- Accept/reject PRs
- Use for: Regular team members

Maintain:
- Write permissions +
- Manage repository settings (limited)
- Manage webhooks
- Manage GitHub Pages
- Use for: Lead developers, team leads

Admin:
- All permissions
- Delete repository
- Transfer ownership
- Manage security settings
- Use for: Project owners, senior leadership

Team-based permission strategy:

# Organization-level teams
@org/developers          - Write access to code repos
@org/leads              - Maintain access to team repos
@org/architects         - Admin access to core repos
@org/contractors        - Read access to specific repos
@org/security-team      - Admin access to security repos

# Best practices
✓ Use teams instead of individual permissions
✓ Follow principle of least privilege
✓ Review permissions quarterly
✓ Remove access promptly when members leave
✓ Use outside collaborators for temporary access
✓ Enable 2FA requirement for organization

Team Workflows and Conventions

Establish clear workflows and conventions for consistency:

Daily Workflow:

Morning:
git checkout main
git pull origin main
Review assigned PRs
Check GitHub notifications

During Development:
Create feature branch from main
Make atomic commits with clear messages
Push regularly (at least daily)
Keep branch updated with main

Before Requesting Review:
Self-review all changes
Run tests locally
Update documentation
Create clear PR description

After Approval:
Squash/merge as per team preference
Delete feature branch
Verify deployment (if automated)

Branch naming conventions:

Consistent Branch Naming:

feature/AUTH-123-user-login
bugfix/CORE-456-memory-leak
hotfix/critical-security-patch
release/v2.3.0
refactor/database-optimization
docs/update-api-reference

Pattern: type/ticket-description
- Use ticket number if available
- Keep description brief but clear
- Use hyphens, not underscaces
- All lowercase

Automation: Use Git hooks or GitHub Actions to enforce branch naming conventions automatically.

Documentation Best Practices

Good documentation is essential for team collaboration:

Documentation Hierarchy:

1. README.md - Quick start and overview
   - What the project does
   - How to install and run
   - Link to detailed docs

2. /docs Directory - Detailed documentation
   /docs
   ├── getting-started.md
   ├── architecture.md
   ├── api-reference.md
   ├── deployment.md
   └── troubleshooting.md

3. Code Comments - Inline documentation
   - Explain WHY, not WHAT
   - Document complex algorithms
   - Add TODO/FIXME with issue numbers

4. API Documentation - For libraries/services
   - OpenAPI/Swagger for REST APIs
   - GraphQL schema documentation
   - Code examples for each endpoint

5. ADRs (Architecture Decision Records)
   /docs/adr
   ├── 001-use-postgresql.md
   ├── 002-adopt-microservices.md
   └── 003-choose-react.md

Documentation in pull requests:

PR Documentation Requirements:

✓ Update README if user-facing changes
✓ Update API docs for endpoint changes
✓ Add/update code comments
✓ Update CHANGELOG.md
✓ Add migration guides for breaking changes
✓ Include screenshots for UI changes
✓ Document configuration changes

Communication and Coordination

Effective communication prevents conflicts and improves collaboration:

Communication Channels:

GitHub Issues:
- Bug reports
- Feature requests
- Task tracking

Pull Requests:
- Code discussions
- Implementation feedback
- Technical decisions

GitHub Discussions:
- General questions
- Ideas and proposals
- Community engagement

Team Chat (Slack/Discord):
- Quick questions
- Daily standups
- Urgent notifications

Video Calls:
- Architecture discussions
- Complex PR reviews
- Sprint planning

Avoiding merge conflicts through communication:

Conflict Prevention Strategies:

1. Communicate early:
   "I'm working on refactoring the auth module"
   Post in team chat or create issue

2. Keep PRs small:
   Merge frequently to reduce overlap
   Aim for 200-300 lines per PR

3. Coordinate on shared files:
   If two people need to edit same file, coordinate timing
   Consider pair programming

4. Update branches regularly:
   Merge main into your branch daily
   Resolve conflicts incrementally

5. Use feature flags:
   Deploy incomplete features behind flags
   Merge to main early, enable when ready

Practice Exercise:

Set Up Team Collaboration:

Create a new repository with README, CONTRIBUTING.md, and .gitignore
Set up branch protection rules for the main branch
Create a CODEOWNERS file with at least 3 patterns
Add a pull request template to .github/
Create issue templates for bugs and feature requests
Set up a basic GitHub Actions workflow for tests
Write documentation for your team's Git workflow
Configure repository permissions for different team roles

Summary

In this lesson, you learned:

Setting up team repositories with proper structure and files
Configuring branch protection rules to enforce quality
Using CODEOWNERS for automatic reviewer assignment
Establishing required review policies and SLAs
Setting up automated status checks for code quality
Managing repository access and permissions effectively
Defining team workflows and naming conventions
Creating comprehensive documentation
Coordinating communication to prevent conflicts

Next Up: In the final lesson, we'll walk through complete real-world scenarios using Git and GitHub in professional development!