fix: cleanup and add social context

Author: lwasser

github-git/edit-commit-files.md

@@ -18,83 +18,97 @@ og:image: /images/github/steps-to-contribute.png
 og:image:alt: An image that shows the steps for contributing to open source on GitHub.
 ---
 
-# Your first edits to a file in your fork
+# Your First Edits to a File in Your Fork: Edit & Commit
 
-:::{todo}
-Github has changed things a bit. If you edit the file in place, it automatically directs you to a pr workflow in the repo that you are in.
-
-So I think we want to break this down into two things
+Now that you've [identified and comment on an issue](identify-issue), [forked the repository](fork-repo) and received approval to work on an issue, it's time to make your changes.  
 
-1. The drive-by pull request
+> **💡 Reminder:** Your fix should be **small and text-based**, like updating documentation or fixing a typo.  
 
-* Click on the edit button in the repo that you want to make changes.
-* If you don't have permission, it will automatically ask you about making a branch, which will be from your fork.
+:::{admonition} What you'll learn  
+:class: tip  
+You’ll edit a file directly in your **fork** using GitHub’s interface and commit the changes  using only the native GitHub interface. 
 
-2. The pr from your fork. If the fork already exists, then you can still edit the file.
+NOTE: If you want to work on the files locally on your laptop, you will need to [clone or make a copy of your repo locally](clone-repo).
 
 :::
 
-In the previous lesson, [you identified something that you wanted to fix in our example GitHub repository](identify-issue). Ideally, the fix that you identified is small, text-based, and can be made by modifying a single file.
+## How to edit a file in your fork  
 
-After you [forked the repository that you want to contribute to](fork-repo) and received approval from a maintainer to work on the issue, it's time to start making the changes you suggested.
+GitHub lets you edit files right in your browser. Here’s how:  
 
-:::{admonition} What you'll learn here
-:class: tip
-In this lesson, you will edit a file in the demo pyOpenSci repository using the GitHub interface in your [forked repo](fork-repo). You will then commit your changes.
-:::
-
-Here, you will make the changes that you proposed to work on using only the native GitHub interface.
-To do this, you do not need to [clone or make a copy of your repo locally](clone-repo).
+1. Navigate to **your fork** of the repository.  
+2. Find the file you want to edit.  
+3. Click the <kbd><i class="fa-solid fa-pencil" style="color: #81c0aa;"></i> Edit</kbd> button.  
+4. Make your changes and **commit** them.
 
 :::{figure} /images/github/edit-commit-file.gif
+:alt: "GIF showing how to edit and commit a file on GitHub."  
 
+Editing a file directly in the GitHub interface is a straight forward process. 
 :::
 
-## About editing files on GitHub
-
-Editing a file on GitHub allows you to focus on the contributing workflow without needing to learn or install git, create a local development environment, or use the command line.
-
-Following this process, you can edit as many files as you wish. However, on GitHub, you must edit and commit changes to them individually.
+> **⚡ Quick tip:** You can edit as many files as you want, but GitHub only lets you commit them **one at a time** in the browser.  
 
-### Editing files on GitHub vs GitHub Codespaces vs Locally
 
-In the above image, you edit the file online at GitHub.com. To do this, you navigate to the page that you want to edit and click on the <kbd><i class="fa-solid fa-pencil"></i></kbd> edit button. This approach is a great way to start contributing as you don't have to
+## Editing files directly on GitHub vs. GitHub Codespaces  
 
-1. use the command line to edit the file
-2. know how to use .git
+GitHub now offers **two ways** to edit files directly in the interface or using the cloud based GitHub Codespaces:  
 
-However, the one small downside of this approach is that you can only edit and commit one file at a time.
+| Option  | When to Use | Pros | Limitations |  
+|---------|------------|------|-------------|  
+| **GitHub Interface** <i class="fa-solid fa-pencil" style="color: #81c0aa;"></i> | Quick edits (typos, small fixes) | No setup needed, edit in browser | Can only commit one file at a time |  
+| **GitHub Codespaces** <i class="fa-solid fa-laptop-code" style="color: #81c0aa;"></i> | Editing multiple files | Full VS Code environment in browser | Requires configuration but once configured, you can reuse it |  
 
-An alternative way to edit multiple files on GitHub is to use GitHub Codespaces.
+> **💡 Need to edit multiple files using a coding editor like VsCode or Jupyter?** Learn more about using [GitHub Codespaces](github-codespaces).  
 
-[GitHub codespaces](github-codespaces) provide online GitHub development environments that allow you to edit multiple files and commit them together using an IDE (interactive development environment) such as VsCode.
-
-Sometimes, maintainers will set up a codespace for you to use. Or, you can also set one up yourself in your fork. GitHub codespaces also come with GitHub setup, which means that you can commit files to your fork within VsCODE vs needing to know how to use the command line.
 
 ## What is a commit?
 
-Here are 3 points to remember when you think about commits:
+You can think of a **commit** as a save (or restore) point in git version control's history. Each commit captures changes that you make to one or more files in the repository at a specific point in time; each commit includes a note explaining what you did. 
+
+:::{tip}
+A **commit** is a feature of [git version control](what-is-git), the version control system that GitHub runs in the background. 
 
-1. A **commit** is a feature of [git version control](what-is-git) that is similar to saving your changes with a note explaining what you did.
+:::
 
-2. Each commit that you make represents a set of changes to one or more files in your repository at a specific time.
+### How commits work
 
 :::{figure}  /images/github/git-commits-files.png
 :alt: A visual example demonstrating how Git tracks changes to a document through commits. The image shows an “Original File” with its initial text, followed by two commits. The first commit adds a new paragraph of text, with the changes highlighted in green and the commit message, “Fix: added a new paragraph to clarify text.” The second commit fixes typos in the text, with the edits highlighted in green and the commit message, “Fix: copy edits.” At the bottom, a comparison shows the document after each commit, illustrating how the file evolves with changes.
 
+Each commit represents **a set of changes** at a specific time. 
 :::
 
-3. Because you are using git, you can always revert or undo a set of changes in your commit history. While undoing things in git takes a bit more knowledge, knowing it can be done can give you the confidence to make changes without worrying about breaking things!
+> **🛠 Do you need to undo changes that you made?** Git lets you revert to an earlier commit, so you don’t have to worry about breaking anything.
+
 
 :::{figure}  /images/github/git-what-are-commits.png
 :alt: A diagram explaining Git commits and their role in version control. The top section shows a timeline of circular commits, each paired with a file icon to represent file changes, with the text: “Each commit represents one or more file changes made at a specific point in time.” The middle section highlights the “Latest Commit” on the timeline, showing it as the current state of the repository. The bottom section demonstrates the concept of reverting, with an arrow pointing from a later commit back to a previous one, illustrating that Git allows reverting or going back to earlier commits. The text reads: “You can also always revert or return to a previous commit. This is what makes Git powerful.”
 
+You can always **undo or revert** changes using Git. 
 :::
 
-## Up next - create a pull request
+## Up next: Make a pull request  
+
+Once you've committed your changes, you can open a **pull request (PR)** to suggest your edits to the main project.  
+
+[Learn how to create a pull request →](pull-request)  
 
-Once you have made the changes to the files that you wish to change in your branch, you are ready to open a [pull request](pull-request). You will learn how to do that next.
 
 :::{todo}
+
 It might be cool to show first contributions like my first on to nbconvert could be interesting? Other people might have examples too from the community that we could share with some stories about it??
+
+
+Github has changed things a bit. If you edit the file in place, it automatically directs you to a pr workflow in the repo that you are in.
+
+So I think we want to break this down into two things
+
+1. The drive-by pull request
+
+* Click on the edit button in the repo that you want to make changes.
+* If you don't have permission, it will automatically ask you about making a branch, which will be from your fork.
+
+2. The pr from your fork. If the fork already exists, then you can still edit the file.
+
 :::

github-git/github-social-platform.md

@@ -13,10 +13,9 @@ kernelspec:
 
 # Community Interaction Best Practices on GitHub
 
-🚧 These lessons are under heavy construction and will continue to change through March 2025 🚧 
 ## Introduction
 
-GitHub is more than just a platform for hosting code—it’s a **social platform** where developers, researchers, and contributors work together to create, improve, and share projects. Behind every username is a person who deserves respect and appreciation. 
+GitHub is more than just a platform for hosting code—it’s a **social platform** where developers, researchers, and contributors work together to create, improve, and share projects. Behind every username is a person who deserves respect and appreciation.
 
 This lesson will teach you how to interact constructively and positively within the GitHub community. Whether submitting an issue, reviewing someone else’s work, or asking for help, following these best practices will help you collaborate effectively and maintain a welcoming environment.
 
@@ -25,16 +24,19 @@ This lesson will teach you how to interact constructively and positively within
 Effective communication on GitHub ensures a productive and respectful collaboration environment. Whether you're raising an issue, reviewing code, or contributing to a discussion, these principles will help you interact constructively.
 
 ### Respect and professionalism
+
 - Treat everyone with respect, even when disagreements arise.
 - Remember that many maintainers and contributors volunteer their time and expertise to the community.
 - Use polite and appreciative language when reaching out or giving feedback.  
   _Example: "Thank you for creating this tool. It's been really helpful!"_
 
 ### Patience
+
 - Be understanding if responses to issues or pull requests take time.
 - Open-source maintainers often juggle multiple responsibilities outside their projects.
 
 ### Clarity and thoughtfulness
+
 - **Use clear and concise language**:  
   - Clearly describe issues, bugs, or suggestions to avoid confusion.
   - Avoid unnecessary jargon or overcomplicating explanations.
@@ -46,19 +48,19 @@ Effective communication on GitHub ensures a productive and respectful collaborat
   - Use **reactions** (like 👍 or ❤️) to express agreement or appreciation without cluttering threads with “+1” comments.
 
 ### Constructive feedback
+
 - Avoid harsh language, blame, or criticism.
 - Frame suggestions as questions or alternatives:  
   _"What if we try this approach?"_ instead of _"This is wrong."_
 - Acknowledge positive aspects alongside suggestions for improvement.
 
 :::{todo}
-Move this to the pr page once I create it. 
+Move this to the pr page once I create it.
 
 ## 3. When Contributing to a Repository
 
-
-
 ### Opening Pull Requests
+
 - **Describe the Change**: Clearly explain what you’re proposing and why it’s needed.
 - **Follow Contribution Guidelines**: Adhere to any style or workflow rules outlined in the repository.
 - **Be Open to Feedback**: Expect to receive suggestions for improvement and revise your pull request accordingly.
@@ -76,10 +78,12 @@ Here are key social cues to follow:
 ### 1️⃣ Help Maintainers Keep Track of Who’s Working on What  
 
 <i class="fa-solid fa-list-check" style="color: #6ec9c3;"></i> **Open an issue first before submitting a PR.**  
+
 - This prevents duplicate work and ensures the maintainers **know who is working on what**.  
 - If an issue already exists, **comment on it** instead of creating a new one.  
 
 <i class="fa-solid fa-triangle-exclamation" style="color: #6ec9c3;"></i> **Avoid surprising maintainers with a PR.**  
+
 - Some projects may not be ready for the change you're suggesting.  
 - Opening an issue first allows maintainers to **provide guidance before you start coding**.  
 
@@ -88,10 +92,12 @@ Here are key social cues to follow:
 ### 2️⃣ Respect the Project’s Process  
 
 <i class="fa-solid fa-book-open" style="color: #6ec9c3;"></i> **Follow issue templates and contribution guidelines.**  
+
 - Many projects have structured templates—**use them** to provide all necessary details.  
 - If guidelines exist, reference them in your issue to show you're **aligning with their workflow**.  
 
 <i class="fa-solid fa-compass-drafting" style="color: #6ec9c3;"></i> **Ask before making major changes.**  
+
 - If your fix changes functionality, check with maintainers before proceeding.  
 - A simple “Would this be useful?” can save **time for both you and the maintainers**.  
 
@@ -100,10 +106,12 @@ Here are key social cues to follow:
 ### 3️⃣ Acknowledge the Maintainers’ Time & Role  
 
 <i class="fa-solid fa-handshake-angle" style="color: #6ec9c3;"></i> **Maintain respectful communication.**  
+
 - Many maintainers **volunteer their time**—make your requests **clear and easy to understand**.  
 - If you're waiting on a response, be patient, and after a reasonable time, you can **politely follow up**.  
 
 <i class="fa-solid fa-user-tag" style="color: #6ec9c3;"></i> **Tag maintainers (when appropriate).**  
+
 - If you know who maintains the repo, consider **@mentioning them** in your issue to establish a connection.  
 - Example: `@maintainer-name, I’d love to help fix this! Any guidance before I start?`  
 
@@ -112,10 +120,12 @@ Here are key social cues to follow:
 ### 4️⃣ Communicate Like You Would in Real Life  
 
 <i class="fa-solid fa-comments" style="color: #6ec9c3;"></i> **Be polite and professional.**  
+
 - Open source is about **collaborating with people you’ve never met**.  
 - Treat maintainers **as you would a colleague**—respectful and appreciative of their time.  
 
 <i class="fa-solid fa-hand-wave" style="color: #6ec9c3;"></i> **Introduce yourself in your first issue comment.**  
+
 - If you’re new, a friendly introduction can make it easier to build relationships.  
 - Example:  
   > “Hey everyone! 👋 I’m new to contributing here and would love to help with this issue. Let me know if there’s anything I should consider before getting started!”  
@@ -125,16 +135,19 @@ Here are key social cues to follow:
 ### 5️⃣ Build Trust Through Small Contributions  
 
 <i class="fa-solid fa-user-check" style="color: #6ec9c3;"></i> **Start small to establish credibility.**  
+
 - First contributions aren’t just about code—they're about **building trust with the community**.  
 - **Small fixes** (like documentation updates or typo corrections) are a great way to get started.  
 
 <i class="fa-solid fa-layer-group" style="color: #6ec9c3;"></i> **Contributions add up over time.**  
+
 - Even small changes **help the project grow** and demonstrate your commitment.  
 - Once maintainers recognize your contributions, they’re more likely to engage with your work.  
 
 ---
 
 ### **✨ Summary: Contribute Thoughtfully & Respectfully**  
+
 ✅ Open issues before submitting PRs to **help maintainers stay organized**.  
 ✅ Follow contribution guidelines to **respect the project’s workflow**.  
 ✅ Communicate professionally to **build relationships in the open-source community**.  

github-git/intro.md

@@ -71,11 +71,11 @@ resources
 :hidden:
 
 0. Your contributing path <your-first-contribution>
-2. Get to know the repo <get-to-know-repo>
-3. Find an issue <identify-issue>
-4. Fork GitHub Repo <fork-repo>
-5. Edit & commit files <edit-commit-files>
-6. Submit Pull Request <pull-request>
+1. Get to know the repo <get-to-know-repo>
+2. Find an issue <identify-issue>
+3. Fork GitHub Repo <fork-repo>
+4. Edit & commit files <edit-commit-files>
+5. Submit Pull Request <pull-request>
 
 :::
 

github-git/pull-request.md

@@ -88,20 +88,20 @@ You can also click on the commit titles to see the specific changes in each comm
 
 ### Step 4: Finalize and submit your PR
 
-Once you've reviewed your PR and evertyhing looks good, it's time to submit it.
+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.
 
-If you go to the parent repotiory you will see the PR listed there.
+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
 
-If you're not ready to submit, you can close a PR anytime via the **Close pull request** button. You can reopen it later if needed.
+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.
 
 ## Who Can Merge a Pull Request?