fix: edits from group review

Author: lwasser

github-git/pull-request.md

@@ -16,7 +16,7 @@ myst_html_meta:
   "property=og:locale": "en_US"
 ---
 
-# How to Submit a GitHub Pull Request
+# About Pull Requests
 
 In the last lesson, you learned how to [make and commit a change to a document in a GitHub repository](edit-commit-files).
 In this lesson, you will learn how to submit a pull request after making changes to a file in a GitHub repository.  
@@ -27,9 +27,14 @@ A GitHub pull request (**PR**):
 1. **Supports Review**: A pull request also triggers a review process where other repository owners and users can review and comment on your changes and suggest edits to your changes line-by-line. This makes incorporateing your changes fully transparent.
 1. **Maintainers to manage contributions**: PRs allow maintainers to document, approve, and merge contributions into the project in a consistent way.
 
+> **<i class="fa-solid fa-handshake-angle" style="color: #81c0aa;"></i> Social cue:** 
+> A pull request is a **collaborative tool**—it lets maintainers review changes 
+> before merging them. PRs **show transparency** and let others give feedback, 
+> making sure every update aligns with the project's goals.   
+
 Pull requests empower you to contribute to the work of others in an open and accessible way, even if you don't have direct access to the repository.
 
-## The steps
+## How to Submit a GitHub Pull Request
 
 ### Step 1: Open your GitHub pull request
 
@@ -64,13 +69,42 @@ In this example, you want to update:
 * **base**: `pyopensci/pyos-demo-package-contribute` with
 * **head**: commits in your fork `your-username/pyos-demo-package-contribute`.
 
+
+> **<i class="fa-solid fa-code-branch" style="color: #81c0aa;"></i> Social Tip:**  
+> Choosing the correct **head** and **base** repositories ensures that your changes 
+> go to the right place. If you accidentally select the wrong base, your PR might not 
+> reach the maintainers you intended. Double-check this before submitting!  
+
 The above pull request configuration tells **GitHub** to update the base repository with contents from your forked repository or the head repository.
 
-### Step 3: Verify changes in your pull request
+
+### Set up a pull request: base vs. head
+
+When creating a **pull request (PR)**, you must define where your changes should be added and where they come from.  
+
+- **<i class="fa-solid fa-database" style="color: #81c0aa;"></i> Base:** The repository where you want your changes to be merged. *(This is usually the original repo you forked.)*  
+- **<i class="fa-solid fa-code-branch" style="color: #81c0aa;"></i> Head:** The repository containing your changes. *(This is your fork. The copy of the repo that you own, where you made edits.)*  
+
+> **🔹 Quick way to remember:** The **head** is "ahead" of the base, meaning it has new changes that the base repository does **not** yet have.  
+
+:::{todo}
+ 
+/images/github/base-vs-head.png  
+:alt: "Diagram showing how base and head work in GitHub pull requests."  
+Create Graphic: Simple diagram with arrows from "Your Fork (Head)" → "Original Repo (Base)"  
+
+:::
+
+### Step 3: Review your own pull request first
 
 When comparing repositories in a **pull request (PR)**, GitHub provides a **diff view** of changes between files (diff as in difference). Before submitting the pr, carefully review these changes to ensure that what you intended to submit is in the PR (and nothing else).
 
-Since others will review your PR, take time to **clean up unnecessary changes** before submitting. your time upfront will lead to the PR being merged sooner and will make it easier for others to review.  
+Since others will review your PR, take time to **clean up unnecessary changes** before submitting. Your time upfront will lead to the PR being merged sooner and will make it easier for others to review.  
+
+> **<i class="fa-solid fa-magnifying-glass" style="color: #81c0aa;"></i> Social cue:**  
+> A PR isn't just about submitting changes—it’s about **communicating clearly** with 
+> maintainers. A well-reviewed PR with **only relevant changes** is easier to merge. 
+> **Check that your PR doesn’t include unintended file modifications.**  
 
 Before you submit your PR, check:
 
@@ -93,20 +127,34 @@ Once you've reviewed your PR and everything looks good, it's time to submit it.
 Add a descriptive title and write a brief description of your changes. Pull request titles should be concise and descriptive of the content in the pull request. When you have added your
 title and description, click on “Create Pull Request” one more time to submit the PR.
 
+> **<i class="fa-solid fa-pen-to-square" style="color: #81c0aa;"></i> Social cue:**  
+> A **clear, descriptive PR title** helps maintainers quickly understand your changes.  
+> A good title is specific: **"Fix typo in README"** is better than **"Updated file"**.  
+> Your description should also **explain why** the change was made.   
+
 If you go to the parent repository, you will see the PR listed there.
 
 :::{tip}
 You can modify the title and description of your pull request at any time - even after you've submitted the pull request.
 :::
 
-## Close a Pull Request
+## Close or move a Pull Request to draft
+
+Sometimes, after opening a pull request, you realize it's **not quite ready for review**. In that case, you have two options:  
 
-You can close a PR anytime via the **Close pull request** button if you're not ready to submit. You can reopen it later if needed.
+1. **<i class="fa-solid fa-file-pen" style="color: #81c0aa;"></i> Convert it to a draft** – A draft pull request signals to maintainers that your PR is **still in progress** and not yet ready for review.  
+2. **<i class="fa-solid fa-xmark" style="color: #81c0aa;"></i> Close the PR** – You can close a PR anytime via the **Close pull request** button and reopen it later when you're ready to submit.  
 
-## Who Can Merge a Pull Request?
+## Who can merge a pull request?
 
 When you create a **pull request (PR)**, GitHub directs you to the parent repository (e.g., the pyOpenSci repo). At the bottom of the PR, a **Merge Pull Request** button appears, which only the **repository owner** or collaborators can use after reviewing your changes.
 
+> **<i class="fa-solid fa-user-shield" style="color: #81c0aa;"></i> Social cue:**  
+> Only maintainers can merge PRs, but **you can make their job easier**!  
+> - **Be responsive** if they ask for changes.  
+> - **Follow repository guidelines** for PR structure.  
+> - **Check for review comments** and update your PR accordingly.   
+
 The repo owner may request modifications before merging. Any future commits to the same branch will be added to the PR until it is merged.
 
 ::: {note}

github-git/your-first-contribution.md

@@ -20,6 +20,10 @@ og:image:alt: An image that shows the steps for contributing to open source on G
 
 # Mastering GitHub Collaboration Skills 
 
+Contributing to open source in a public space like GitHub can feel intimidating. You may not know the project maintainers, feel unsure about your GitHub skills, or wonder where to begin.
+
+This lesson series will teach you how to collaborate on code and documentation using GitHub. It will help you confidently contribute to a GitHub repository and build skills to collaborate with colleagues (some of whom you may not have met in real life!). 
+
 (first-contribution)=
 
 ## Get started with your first open source contribution 
@@ -174,9 +178,14 @@ Once your PR is open, it's time to sit back and wait for the maintainers, collab
 
 ## Many people's first contributions are to documentation 
 
-In this lesson, you make your first open source contribution by updating documentation (including docstrings) rather than code. Many people start with small fixes like typos, which are simpler to contribute as you don't always need a development environment but are still valuable. Developers often focus on code, leaving less time for writing and editing documentation. So your small contributions can have a large impact.
+In this lesson, you make your first open source contribution by updating documentation (including docstrings) rather than code. Many people start with small fixes like typos, which are simpler to contribute as you don't always need a development environment but are still **highly valuable**. 
+
+### <i class="fa-solid fa-rocket"></i> Fresh eyes make a difference! <i class="fa-solid fa-rocket"></i>
+
+When you’re new to a project, you may notice gaps and unclear explanations that long-time contributors might overlook. Maintainers and developers are often too close to their own work to see what’s missing. Your perspective helps make the project more accessible to future contributors.
+
+By catching confusing phrasing, outdated information, or missing details (even in contributing documentation), you improve the onboarding experience for others while making a meaningful first contribution!
 
-Further, if you go to contribute and find that the contributing guidelines lack detail, that could also be a useful place for you to start. 
 
 :::{admonition} A real-life first contribution to PyPI