Scenario 5 — Full PR Workflow

# Scenario 5 — Full PR Workflow ## The brief Practice the full open-source / team workflow. Fork → branch → change → push → open PR → review → merge → cleanup. If contributing to OSS, use a beginner-friendly repo (e.g., a "good first issue" on a real project). For internal practice: pair with a teammate or use your own two GitHub accounts. ## Step 1: Pick a repo (5 min) For practice without contributing to OSS: create a repo and invite a teammate as a collaborator. For OSS practice: find an issue labeled "good first issue" on a small project. firstcontributions.github.io has options. ## Step 2: Fork (5 min) On GitHub: - Click "Fork" on the upstream repo. - Creates a copy under your account. ```bash git clone git@github.com:yourname/the-repo.git cd the-repo # Set up upstream remote for syncing git remote add upstream git@github.com:original-owner/the-repo.git git remote -v # origin git@github.com:yourname/... (your fork) # upstream git@github.com:original-owner/... (the source) ``` ## Step 3: Create a branch (5 min) ```bash git switch main git pull upstream main # sync with source git push origin main # update your fork's main git switch -c fix/typo-in-readme # short, descriptive branch name ``` ## Step 4: Make a change (15 min) For practice, a typo fix is fine: - Find a typo in README.md or docs. - Fix it. - (Don't fabricate typos to "fix"; many OSS maintainers find this annoying. Focus on real issues.) For a real PR: - Read the issue description. - Understand the existing code. - Make minimal changes. - Add tests if applicable. Commit: ```bash git add README.md git diff --staged # double-check changes git commit -m "Fix typo in README installation section" ``` ## Step 5: Push to your fork (5 min) ```bash git push -u origin fix/typo-in-readme ``` GitHub shows a link to open a PR. Or visit your fork's page. ## Step 6: Open the PR (15 min) On GitHub: - "Compare & pull request" button. - Base: upstream/main; head: yourname/fix/typo-in-readme. Fill the description: ```markdown ## Summary Fixes a typo in the README's installation section ("inrstall" → "install"). ## Why Found while reading the docs. Minor but visible. ## Test N/A (docs change). ## Related Closes #234 (if applicable). ``` Submit. ## Step 7: Get reviewed (15 min) Reviewer comments: - "Can you also update CONTRIBUTING.md which has the same typo?" - "[nit] Maybe also fix similar typo on line 50?" Respond: - Make the changes: ```bash # Edit files git add CONTRIBUTING.md git commit -m "Fix same typo in CONTRIBUTING.md" git push ``` - Reply to comments: - On the request for CONTRIBUTING.md: "Updated, ready for re-review." - On the nit: "Good catch — fixed in same commit." Re-request review via GitHub. ## Step 8: Approval and merge (5 min) After approval: - Reviewer (or you, if you have permission) clicks "Squash and merge" (or "Merge commit", depending on repo). - Optional: edit the merge commit message. The PR is merged into upstream/main. ## Step 9: Cleanup (5 min) ```bash git switch main git pull upstream main # bring the merged change into local main git push origin main # update your fork git branch -d fix/typo-in-readme # delete local branch git push origin --delete fix/typo-in-readme # delete remote branch ``` Your fork's main matches upstream/main. Branch is gone everywhere. ## Step 10: Sync your fork periodically For ongoing contribution: ```bash git switch main git fetch upstream git merge upstream/main # or rebase git push origin main ``` Keeps your fork in sync. ## Deliverables - A merged PR (link). - A `WORKFLOW.md` describing: - The fork-branch-PR cycle. - How to keep a fork in sync. - How to respond to review comments. - Squash and merge vs merge commit. ## What you'll learn - The full PR workflow (the daily reality of most devs). - Fork vs branch (forks for OSS; branches for team repos). - Sync upstream → fork. - Responding to code review. - Cleanup after merge. ## Stretch - Make a non-trivial PR (real feature or bug fix). - Practice with a teammate as reviewer; reverse roles. - Add a CODEOWNERS file to a repo and trigger auto-review-request. - Use `gh pr create`, `gh pr view`, `gh pr merge` for the full CLI workflow.