GitHub Workflow

GitHub Flow — The Industry Standard

GitHub Flow is a lightweight, branch-based workflow that teams use everywhere from startups to Fortune 500 companies. It has one rule: main is always deployable. All work happens in branches and only lands in main via a Pull Request.

# 1. Start from latest main
git switch main
git pull origin main

# 2. Create your feature branch
git switch -c feat/user-auth

# 3. Make commits as you work
git add .
git commit -m "feat: add JWT authentication middleware"

# 4. Push your branch to GitHub
git push -u origin feat/user-auth
# GitHub will suggest opening a Pull Request — click the link!

Creating Pull Requests

A Pull Request (PR) is a formal request to merge your branch into another (usually main). It's where code review happens — teammates can see exactly what changed, comment on specific lines, and approve or request changes before merging.

On GitHub, after pushing your branch you'll see a yellow banner: "Compare & pull request". Click it, then fill in:

Title: Clear and concise — "feat: add user authentication with JWT" is better than "auth stuff"
Description: What does this PR do? Why was it needed? Any caveats?
Reviewers: Tag specific teammates who should review
Labels: bug, enhancement, documentation, etc.
Linked Issues: Use Closes #42 to auto-close an issue when merged

Code Review

Code review is one of the most valuable practices in software development. It catches bugs before production, spreads knowledge through the team, and maintains code quality standards. As a reviewer, your goal is to be constructive, not critical.

Review states: Comment (general feedback, no decision), Approve (looks good, ready to merge), Request Changes (must be addressed before merging). Most teams require at least one approval before merging to main.

Forking Repositories

Forking creates your own copy of someone else's repository on GitHub. Unlike cloning (which just downloads), a fork is a full GitHub repo under your account that you can push to freely. Forks are the foundation of open source contribution.

# 1. Fork on GitHub (click the Fork button on the repo page)
#    This creates: github.com/YOUR_USERNAME/original-repo

# 2. Clone YOUR fork (not the original)
git clone git@github.com:YOUR_USERNAME/original-repo.git
cd original-repo

# 3. Add the original as "upstream" remote
git remote add upstream git@github.com:ORIGINAL_OWNER/original-repo.git

# 4. Create a branch for your change
git switch -c fix/typo-in-readme

# 5. Make your change, commit it
git add . && git commit -m "fix: correct typo in installation guide"

# 6. Push to YOUR fork
git push origin fix/typo-in-readme
# Then open a PR from YOUR fork to the ORIGINAL repo on GitHub

# Keep your fork up to date with upstream changes
git fetch upstream
git merge upstream/main

GitHub Issues

GitHub Issues are the task tracker built into every repository. Use them to report bugs, request features, ask questions, or plan work. Issues integrate tightly with PRs — you can automatically close an issue when a PR merges.

Labels help categorize issues: bug, enhancement, good first issue, help wanted, documentation. The good first issue label is used by open source projects to mark beginner-friendly tasks — a great way to start contributing.

Milestones group issues by version or sprint: "v2.0 Release" or "Sprint 3". They give a high-level view of how much work is done vs remaining toward a goal.

Branch Protection Rules

Branch protection rules prevent accidental or unauthorized changes to critical branches. Most teams protect main so no one can push directly — all changes must go through a PR.

With branch protection enabled, even if you have write access to the repo, git push origin main will be rejected with a "protected branch" error. This forces the PR workflow and prevents the classic "whoops, pushed broken code to production" scenario.

Resolving PR Conflicts

When a PR can't be merged because main has moved ahead and the changes conflict, you need to resolve the conflicts locally and push again. There are two approaches: merge (simpler) or rebase (cleaner history).

### Option 1: Merge approach (simpler)
git switch feat/my-feature
git fetch origin
git merge origin/main
# Resolve any conflicts in your editor
git add .
git commit -m "merge: sync with main"
git push

### Option 2: Rebase approach (cleaner history)
git switch feat/my-feature
git fetch origin
git rebase origin/main
# Resolve conflicts if any, then:
git rebase --continue
git push --force-with-lease
# Use --force-with-lease, not --force (safer)