Team Git Workflow SOP - CMPUT301F25quartz/quartz-events GitHub Wiki

Team Git Workflow SOP

Purpose: A clear, repeatable Git/GitHub workflow that junior engineers can follow to ship features safely without breaking production. Copy this doc into your repo’s /docs/ folder as GIT_WORKFLOW.md.

1) Goals & Principles

  • Protect production: main is always deployable.
  • Integrate early/often: merge work into dev behind CI checks.
  • Small, reviewable changes: short‑lived branches, minimal diff size.
  • Single source of truth: all changes land via Pull Requests (PRs).
  • Reversible: prefer git revert over history‑rewriting on shared branches.

Common misconception to fix: Don’t create a random folder then run git init for an existing GitHub project. Correct is git clone <repo-url> (it creates the folder for you and sets remotes).

2) Branch Model (Lightweight Gitflow)

  • main → production branch (protected). Tagged releases come from here.
  • dev → integration branch (protected). PR targets land here first.
  • feature/<ticket-id>-<short-name> → personal short‑lived branches off dev.
  • hotfix/<issue> → urgent fix branched from main, then merged back into both main and dev.
  • (Optional) release/<version> → stabilization branches if you need freeze windows.

3) One‑Time Local Setup

git clone https://github.com/<org>/<repo>.git
cd <repo>
git remote -v
git fetch origin
git checkout main && git pull --ff-only
git checkout -b dev origin/dev

# Configure identity
git config user.name "Your Name"
git config user.email "[email protected]"

4) Starting a Feature

git checkout dev && git pull --ff-only
git checkout -b feature/123-login-form
git add <files>
git commit -m "feat(auth): add basic login form (closes #123)"
git push -u origin feature/123-login-form

5) Keeping Feature Branch Up to Date

Preferred:

git checkout dev && git pull --ff-only
git checkout feature/123-login-form
git rebase dev
git push --force-with-lease

Alternative:

git checkout feature/123-login-form
git merge dev
git push

6) Opening a Pull Request (PR → dev)

  1. Push your branch.
  2. Open PR on GitHub: base=dev, compare=feature/....
  3. Fill out PR template (below).
  4. Request reviewers.
  5. Wait for CI checks.

7) Code Review Checklist

[] Correctness
[] Tests pass
[] Style/lint
[] Security/privacy
[] Docs updated
[] Focused diff size

8) Merging & Releasing

git checkout main && git pull --ff-only
git merge --ff-only origin/dev
git tag -a v1.3.0 -m "Release 1.3.0"
git push origin v1.3.0

9) Hotfix Workflow

git checkout main && git pull --ff-only
git checkout -b hotfix/critical-bug
# commit fix
git push -u origin hotfix/critical-bug
# PR → main; after merge, sync dev
git checkout dev && git pull --ff-only && git merge --ff-only origin/main && git push

10) Undo & Recovery

git reset --soft HEAD~1         # undo last commit
git revert -m 1 <merge-sha>      # revert shared merge
git reflog                       # find lost commits

11) Daily Checklist

  1. git pull latest dev.
  2. Rebase feature.
  3. Commit small changes.
  4. Push and refresh PR.
  5. Fix CI, review peers.

12) GitHub Protections

  • Protect main & dev
    • Require PR & 1+ review
    • Require passing checks
    • Disallow force push & delete
  • Enable automatic branch deletion
  • Add PR template & CODEOWNERS

13) Quick Command Reference

git clone <url>
git checkout -b feature/<name> dev
git add -A && git commit -m "message"
git push -u origin feature/<name>
git rebase dev && git push --force-with-lease

14) PR Template Example

Save this as .github/pull_request_template.md

### 🧾 Summary
Briefly describe what this PR does and why.

### 🔍 Related User Stories
Closes #US.1.2.3

### 🧪 Testing
- [ ] Ran unit tests locally
- [ ] Verified UI manually (screenshots below)

### ⚙️ Changes
- Added ...
- Modified ...
- Removed ...

### Checklist
- [ ] Code builds locally
- [ ] Tests added/updated
- [ ] Docs updated (README / Wiki)
- [ ] No console/log errors

### Screenshots (if UI changes)
_Attach before/after images._

15) CODE REVIEW COMMAND

gh pr checkout 123 # This command automatically fetches the branch and switches to it


 CODEOWNERS Example

> **Purpose:** Automatically request review from code owners for changes in specific areas. GitHub will auto‑assign reviewers based on this file.

Save as `.github/CODEOWNERS`:

```text
# CODEOWNERS — assign reviewers for specific paths
# Format: <file-path-pattern> <GitHub-username(s)>

# Frontend team
/frontend/   @team-frontend @dims

# Backend team
/backend/    @team-backend

# Android app
/app/        @android-lead

# Configuration or CI
*.yml        @devops-lead

16) Optional: Releases & Versioning

Use Semantic Versioning (MAJOR.MINOR.PATCH) and changelogs. Example tags:

v1.2.0 → new features
v1.2.1 → bug fixes only

Final Notes

Keep PRs under ~300 lines, automate lint/tests, and document design decisions (/docs/adr/).

Copy‑ready for onboarding new contributors.

⚠️ **GitHub.com Fallback** ⚠️