fix: edits from group review

Author: lwasser

github-git/fork-repo.md

@@ -24,7 +24,7 @@ myst_html_meta:
 ---
 
 (fork-repository)=
-# How to Fork a GitHub Repository 
+# A Guide to Forks on GitHub Forks
 
 
 :::{admonition} What You Will Learn  
@@ -49,6 +49,8 @@ Forking a repository **creates a copy** in your GitHub account while keeping a l
 When you fork a GitHub repository, you make a copy of the files and the commit history into your personal account. This allows you to work on the files independently before suggesting changes through a pull request to make to the parent repository you forked from.
 :::
 
+By forking, everyone collaborates on their own copies of the project, ensuring the original files stay intact. All changes are tracked in the file history and can be undone if needed. You can fork a repository directly from its main page on GitHub.com.
+
 ## How to fork a GitHub repository
 
 To fork a GitHub repository:
@@ -74,22 +76,6 @@ The number next to the <kbd><i class="fa-solid fa-code-fork"></i> button tells y
 To fork a repo, navigate to it on GitHub and click the **Fork** button. Your copy will appear under your account.  
 :::
 
-### Setting 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)"  
-
-:::
 
 :::{admonition} Who owns the repo? 
 
@@ -101,7 +87,7 @@ Every GitHub repository has an **owner**, which can be:
 The **owner’s username appears first in the URL**, showing who controls the repository.  
 
 **Example**:  
- - A personal repo: `https://github.com/lwasser/my-project`  
+ - A personal repo: `https://github.com/your-gh-username/my-project`  
  - An organization-owned repo: `https://github.com/pyOpenSci/repo-name`  
 
 If you **fork a repo**, your GitHub username becomes the owner of the fork:  
@@ -110,6 +96,7 @@ If you **fork a repo**, your GitHub username becomes the owner of the fork:
 
 :::
 
+
 ## What happens after you fork a repo?  
 
 Your fork **is a separate copy**, but it remains linked to the original repository.  
@@ -125,7 +112,7 @@ Your fork **is a separate copy**, but it remains linked to the original reposito
 ::::{todo}
  /images/github/fork-structure.png  
 :alt: "Diagram showing how forking creates a personal copy linked to the original."  
-# [Graphic Suggestion: A simple diagram showing "Original Repo → Fork → Your Account".]  
+Graphic: A simple diagram showing "Original Repo → Fork → Your Account".  
 ::::
 
 
@@ -141,16 +128,16 @@ To sync a GitHub fork:
 :::{todo} 
 /images/github/sync-fork.png  
 :alt: "GitHub interface showing how to sync a fork with the original repo."  
-# [Graphic Suggestion: Screenshot of GitHub’s "Sync Fork" button.]  
+Graphi:  Screenshot of GitHub’s "Sync Fork" button  
 :::
 
 ---
 
 ## Takeaways  
 
 ✅ **Forking creates a personal copy of a repository** that you can edit freely.  
-✅ **Your fork stays linked** to the original, allowing you to propose changes.  
-✅ **Sync your fork regularly** to keep it up to date.  
+✅ **Your fork stays linked** to the original repo, allowing you to propose changes.  
+✅ **Sync your fork regularly** to keep it up to date if you plan to contribute to the repo more over time.  
 
 :::{admonition} Next steps  
 :class: important  
@@ -159,8 +146,3 @@ Now that you’ve forked a repository, the next step is to **edit a file and com
 [Learn how to edit and commit files →](edit-commit-files)  
 :::
 
-
-
-
-
-

github-git/identify-issue.md

@@ -24,7 +24,7 @@ myst_html_meta:
 
 Contributing to an open source project starts with identifying an issue to work on. Open issues help developers track bugs, new features, or needed improvements in a repository. Whether you have a specific fix in mind or are looking for ideas, exploring existing issues is the best place to start.  
 
-As discussed in the [get to know a repo lesson](labels-responsive), the way issues are labeled and organized can both help you find issues that maintianers want help with and also tell you a lot about a project. If you see 
+As discussed in the [get to know a repo lesson](labels-responsive), the way issues are labeled and organized can both help you find issues that maintainers want help with and also tell you a lot about a project. If you see 
 beginner-friendly labels like **"good first issue"** or **"help wanted,"** it's a clear signal that the maintainers welcome new contributors. Further those might be good issues for you to start working on!  
 
 :::{figure} /images/github/github-issues-good-first-issue.png  
@@ -37,24 +37,43 @@ new contributors to work on during these events.
 
 This lesson guides you through **finding or creating an issue** in a repository you don’t own. 
 
+## How to find an issue to work on 
 
-## Start by scanning existing project issues 
+Generally, when you start contributing, there are two pathways: 1) you already have an issue in mind that you want to work on, or 2) you don't know what you want to work on yet; you'd like to see what the project needs first. Regardless of the pathway that you take, you'll want to remember two things:
 
-When contributing to a new open source project, the best place to start is by **scanning open issues**. This helps you find tasks maintainers need help with and ensures you don’t duplicate existing work.  
+1. You always want to search for existing issues before opening a new one
+2. You want to link the work you do in a pull request back to the issue you worked on.
 
+Both steps above make it easier for maintainers to keep their list of issues organized and to close issues as they are addressed. 
 
-### 1. You already have identified an issue 
+> **<i class="fa-solid fa-magnifying-glass" style="color: #81c0aa;"></i> Social cue:**  
+> Regardless of your pathway, you'll spend some time searching through issues. You want to demonstrate your willingness to put in effort before raising an issue.  
+> Showing that you’ve already searched first is a great way to show goodwill to maintainers.  
 
-Sometimes, while using a project or reading its documentation, you notice a bug, typo, or improvement. Before starting to work on it, check if the issue **already exists** in the repository.  
+Below, you'll learn how to navigate both pathways.
 
-- **If the issue exists**, leave a comment to let others know you're interested in working on it.  
+### 1. You already have identified an issue that you want to work on
 
+Sometimes, while using a project or reading its documentation, you notice a bug, typo, or improvement. Before starting to work on it, check if the issue **already exists** in the repository.  
 
+- **If the issue exists**, leave a comment to let others know you're interested in working on it.
+  
 Your comment might look like this:  
 
-> Hey maintainer team 👋. I’d like to work on this issue. Is there anything specific I should consider before getting started?  
+> Hey, maintainer team 👋. I’d like to work on this issue. Is there anything specific I should consider before getting started?
+
+- **If it doesn’t exist**, you can [create a new one](create-issue) (*see below*).  
+
+
+### Tips for effectively searching through GitHub issues 
+
+Before opening a **new** issue, check whether the problem has already been raised by searching through both **open** and **closed** issues. When searching, consider the following:
+
+- **<i class="fa-solid fa-keyboard" style="color: #81c0aa;"></i> Use relevant keywords**: Search for terms related to the problem, including specific error messages, function names, or terms like documentation, typos, etc.  
+- **<i class="fa-solid fa-file-circle-xmark" style="color: #81c0aa;"></i> Check closed issues**: Sometimes, an issue has already been discussed and resolved—or maintainers may have decided not to address it.  
+  So be sure to scan both open and closed issues returned in a search.  
+- **<i class="fa-solid fa-code" style="color: #81c0aa;"></i> Search using symbols or variable names**:  Searching for specific variable names or function signatures can help find related discussions if the issue is related to code.  
 
-If the issue you identified doesn't exist yet, you can create a new one. You will learn how to do that below. 
 
 > **<i class="fa-solid fa-handshake-angle" style="color: #81c0aa;"></i> Social Cue:** Opening an issue (or commenting on an existing one) helps maintainers track who is working on what and prevents duplicate work. It also ensures the issue can be properly closed once your pull request is merged. A PR without an issue might catch maintainers off guard, so confirming before starting makes collaboration smoother.  
 
@@ -63,18 +82,31 @@ If the issue you identified doesn't exist yet, you can create a new one. You wil
 
 If you don’t have a specific issue in mind, explore the **open issues** list to find something that interests you. A great place to start is by looking for labels like **"good first issue"** or **"help wanted"**—these are beginner-friendly and often well-scoped.  
 
-- **Start small**—fixing typos, improving documentation, or tackling minor bugs are great first contributions.  
+- **Start small**—fixing typos, improving documentation, or tackling minor bugs are great first contributions. The better scoped your issue is, the easier it will be for you to complete the work and get it merged.  
 - **Leave a comment** on the issue to let maintainers know you'd like to help.  
-
-:::{tip}  
-Leaving comments in a new repository can feel intimidating, but most 
+ 
+> **<i class="fa-regular fa-clock" style="color: #81c0aa;"></i> Social cue:** Leaving comments in a new repository can feel intimidating, but most 
 maintainers appreciate respectful communication and enthusiasm. If a project 
 isn’t open to contributions, they will let you know—and there are plenty of 
-other projects to explore!  
-:::  
+other projects to explore!
 
-(create-issue)=
+### How to know if an issue is available to work on 
+
+Even if you find an open issue that interests you, it’s important to check if someone is already working on it.  
 
+- **<i class="fa-solid fa-comments" style="color: #81c0aa;"></i> Look for comments from other contributors**:  
+  Check if someone has already offered to take on the issue.  
+- **<i class="fa-solid fa-clock-rotate-left" style="color: #81c0aa;"></i> Check the timestamps**:  
+  The issue may still be available if someone commented months ago but never submitted a fix.  
+- **<i class="fa-solid fa-circle-question" style="color: #81c0aa;"></i> If in doubt, ask!**  
+  Leaving a comment like *"Is this issue still open for contributions?"* can clarify things.  
+
+> **<i class="fa-solid fa-hourglass-half" style="color: #81c0aa;"></i> Social cue:**  
+> Just because someone expressed interest in an issue doesn’t always mean they are actively working on it.  
+> If the last comment is old, the contributor may have moved on. Asking politely shows respect for their effort.  
+
+
+(create-issue)=
 ## How to create a new issue
 
 If an issue doesn’t already exist for the thing you'd like to work on, here’s how to create a new one:
@@ -86,11 +118,24 @@ If an issue doesn’t already exist for the thing you'd like to work on, here’
 Some projects use templates for reporting **bugs, documentation fixes, or new features**. If a template is available, fill it out—it helps maintainers quickly understand your issue.  
 ::: 
 
-4. Create a **clear title** summarizing what you’d like to fix.  
-5. Be **specific about what you'd like to fix**:  
-   - Explain the problem or fix you’re proposing.  
-   - For **bugs**, include steps to reproduce the issue.  
-   - For **documentation**, link to the page and describe what you’d like to update or enhance. 
+3. Create a **clear title** summarizing what you’d like to fix.
+
+:::{admonition} Examples of Good vs. Less Useful Issue Titles
+
+| | ✅ Good Issue Titles                        | 🚫 Less Useful Titles  |
+|-|-------------------------------------------------|---------------------------|
+|| Add: update docstring in the `function_name_here()` function.| Update documentation. |
+|| Fix: Typo in the documentation page for `doc-page-here`. | Fix formatting. |
+|| Fix: Bug in `xxx` module that causes `x, y, z` to happen. | This feature is broken. |
+|| Update the `module_name.py` module with a clearer docstring. | Bad UI, please fix. |
+:::
+
+4. Be **specific about what you'd like to fix**:
+  * Ideally, the issue that you want to address focuses on one thing and isn't too broad. 
+  * Explain the problem or fix you’re proposing.  
+  * For **code bugs**: include steps to reproduce the issue; also describe what you expected would happen, and what actually happened when you ran the code.  
+  * For **documentation**: link to the page and describe what you’d like to update or enhance.
+  * For **new features**: describe what will happen once it is implemented
 
 :::{figure} /images/github/open-issue.gif
 :alt: alt text here
@@ -102,24 +147,18 @@ Some projects use templates for reporting **bugs, documentation fixes, or new fe
 
 Maintainers are often volunteers, so the more information you provide, the easier it is for them to support you. A well-crafted issue saves time and helps get faster responses.
 
-**<i class="fa-solid fa-magnifying-glass" style="color: #6ec9c3;"></i> Social Cue:** Before submitting the issue, ask yourself:
- * Could someone unfamiliar with the project understand this issue?
- * Did I provide enough detail for a maintainer to respond without extra questions?
+>**<i class="fa-solid fa-magnifying-glass" style="color: #6ec9c3;"></i> Social Cue:** Before submitting the issue, ask yourself:
+> * Could someone unfamiliar with the project understand this issue?
+> * Did I provide enough detail for a maintainer to respond without extra questions?
 :::
 
-## Examples of Good vs. Less Useful Issue Titles
-
-| ✅ Good Issue Titles                        | 🚫 Less Useful Titles  |
-|-------------------------------------------------|---------------------------|
-| Add: update docstring in the `function_name_here()` function.| Update documentation. |
-| Fix: Typo in the documentation page for `doc-page-here`. | Fix formatting. |
-| Fix: Bug in `xxx` module that causes `x, y, z` to happen. | This feature is broken. |
-| Update the `module_name.py` module with a clearer docstring. | Bad UI, please fix. |
-
-
 > **<i class="fa-solid fa-user-tag" style="color: #6ec9c3;"></i> Social Cue:** For smaller projects, tagging a maintainer can help get feedback faster. However, check contributor guidelines first to see if this is encouraged. Example:  
-> `@maintainer-name, I'd love to help with this! Let me know if there's anything I should consider before starting.`  
+> `@maintainer-name, I'd love to help with this! Let me know if there's anything I should consider before starting.`
 
+ 
+:::{todo}
+Add section on issue templates, how they work, what they are
+:::
 
 ### After you've opened an issue