Reorg of lessons

Author: lwasser

github-git/0-first-contribution.md

@@ -16,14 +16,6 @@ kernelspec:
 
 🚧 These lessons are under heavy construction and will continue to change through March 2025 🚧 
 
-:::{todo}
-
-what's missing
-* Create a new branch to work on in your fork -- don't make a pr from your main or master branch
-* Closes or addresses #issue number
-:::
-
-
 :::{admonition} What you will learn
 
 After completing this tutorial, you will be able to:
@@ -33,38 +25,30 @@ After completing this tutorial, you will be able to:
 You can use the [pyOpenSci example GitHub repository](https://github.com/pyOpenSci/pyos-demo-package-contribute) to practice making contributions for all of these lessons. 
 :::
 
-Contributing to open source software can feel intimidating.  
+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.
 
-* You may not know the project maintainers.  
-* You might feel unsure about your Git and GitHub skills (imposter syndrome is real!).  
-* You may not know where to begin.  
-
-This lesson series will teach you how to collaborate using GitHub, helping you confidently contribute to open source repositories and collaborate with colleagues. 
+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 whome you may not have met in real life!). 
 
 ## GitHub workflow summary
 
-The GitHub contribution workflow looks something like this:
-
-* First, you need to identify a repository that you want to contribute to. Here, you can use the [pyOpenSci learning repository](https://github.com/pyOpenSci/pyos-demo-package-contribute) to test your skills! 
-* Once you have found a repo that you want to contribute to, you need to [get to know it](get-to-know-repo). Getting to know a repo starts with reading the [contributing guide](contributing).
-* Next, you will [identify an issue or bug that you want to work on](identify-issue). This will involve either reading through open issues and finding good first ones to work on. Or maybe you know the repository and already have a fix in mind that you want to implement. In this case, you will [create a new issue](create-issue) in the repo. 
-* Once you have created an issue or identified what you wish to work on, you need to [`Fork` or create a copy of the repo](fork-repository) in your GitHub account.
 
+:::{figure} /images/github/steps-to-contribute.png
+:alt: alt text here
 
-:::{tip}
-If you have already forked the repository but some time has passed. You should consider updating or syncing your fork. GitHub has a sync button that you can use to do this (`pyopensci/repo-name`). This will ensure that all of the files in your repository are current and will prevent merge conflicts.
+To fork a repo, first, navigate to the repo you want to fork. Then click the **fork** button in the upper right-hand corner of your screen. You can then create a copy of this repo in your account.
 :::
 
-:::{todo}
-The section below needs work and to be fleshed out. PR page doesn't exist yet. 
-:::
+Your GitHub contribution workflow will be something like this:
+
+1. First, you will identify a repository you want to contribute to. Here, you can use the [pyOpenSci learning repository](https://github.com/pyOpenSci/pyos-demo-package-contribute) to test your skills. 
+    * You will [get to know that repository](get-to-know-repo) which starts with reading the [contributing guide](contributing). This guide should provide some instructions on how to make your first contribution.
+1. You will [identify an issue or bug that you want to work on](identify-issue). This will involve either reading through open issues and finding good first ones to work on. If you already have a fix in mind that doesn't exist in the existing issue list, you will [create a new issue](create-issue) in the repo. 
+1. Once you have created an issue or identified what you wish to work on, you will [`Fork` or create a copy of the repo](fork-repository) in your GitHub account.
+1. In your fork, you will edit the file(s) addressed in your issue. In this lesson series, you will do [all of the work in the GitHub interface](4-edit-commit-files), which means that you don't have to [clone (or copy)](6-clone-repo) the repo locally to your computer. 
+1. Once your edits are complete, you will commit the changes and open a <kbd>Pull Request</kbd> to the parent repository.  
+     * Finally, wait for the developers to review/comment on your PR. Be patient; this step can take time as people are busy and often donate their time to this effort!
 
-* Create a new branch to work on
-* Make the changes to the file you proposed to change in your issue to the file in the new branch you created. If the changes are to documentation, be sure to spell check!
-* Commit the changes to your fork.   
-* Open a <kbd>Pull Request</kbd> to the parent repository`. In the text of the pull request, you should include a link to the URL of the issue you opened (essentially linking the changes you are submitting to the problem you are solving). This closes the documentation loop! 
-* Finally, wait for the developers to review/comment on your PR. Be patient; this step can take time as people are busy and often donate their time to this effort!
 
-## Your first step: Get to know the repo 
+## Time to get started!
 
-Your first step in making a contribution to a repository that you don't own is [getting to know the repo. You will do that next.](get-to-know-repo)
+Your first step in contributing to a repository you don't own is [getting to know the repo. You will do that next.](get-to-know-repo)

github-git/1-get-to-know-repo.md

@@ -16,39 +16,34 @@ kernelspec:
 
 :::{admonition} What you will learn:
 
-In this tutorial, you will find the CONTRIBUTING.md file in our [example GitHub repo](https://github.com/pyOpenSci/pyos-demo-package-contribute) and identify the process for submitting a contribution to the repo. 
-
+In this tutorial, you will get to know a GitHub repo that you want to contribute to. You will learn how to find the CONTRIBUTING.md file in our [example GitHub repo](https://github.com/pyOpenSci/pyos-demo-package-contribute) and identify the process for submitting a contribution to the repo. 
 :::
 
-The first step in contributing to open source is finding and getting to know the GitHub repository where the code is stored. 
-
-In this case, you will practice contributing to a sample pyOpenSci repository where you are set up to be successful and can practice without worrying about making mistakes. Making mistakes is often the best way to learn. 
 
 (contributing)=
 ## Get started
 
-To begin, you should get to know the repository that you want to contribute to. To do this:
-
-1. **Read the contributing guide**: In the repository, you should see a [**CONTRIBUTING.md** file](https://github.com/pyOpenSci/pyos-demo-package-contribute/blob/main/CONTRIBUTING.md) that tells you more about the types of contributions the project accepts and the workflows it embraces.
+To begin, get to know the repository that you want to contribute:
 
+* **Check out the README file**: Check out the [**README.md** file](https://github.com/pyOpenSci/pyos-demo-package-contribute/blob/main/README.md) to learn more about the project, how it's used and often, it will guide you to the project's contributing and development guides for making contributing if they exist.  
+* **Read the contributing guide**: The [**CONTRIBUTING.md** file](https://github.com/pyOpenSci/pyos-demo-package-contribute/blob/main/CONTRIBUTING.md) that tells you more about the types of contributions this project accepts and the workflows it embraces.
 
 :::{figure} /images/github/github-contributing-file.png
-:alt: Alt here
+:alt: "Screenshot of the GitHub repository ‘pyos-demo-package-contribute’ showing files and folders, including README.md, CONTRIBUTING.md, and LICENSE. The sidebar highlights metadata, such as the repository description, links, and license details. The README.md and CONTRIBUTING.md files are highlighted."
 
+Above is a screenshot of the pyOpensci practice repo that you will use. Notice the CONTRIBUTING.md file. You should read this file after checking out the README file. 
 :::
 
-1. **Read through the documentation**: Most people's first contribution is to documentation. This is a great place to start because typos and other issues often make for great first pull requests. You can often make the changes fully in the GitHub interface online versus needing to clone the repository and work locally.
+## Documentation counts! 
 
-Also, let's face it--code can be scary for some as a first contribution. Don't sweat it if you aren't ready to contribute to the code; you will get here! 
+Many people's first contributions are to documentation! Documentation contributions can be incredibly valuable as developers often don't have time to work on documentation and code!
 
-1. Read through the open issues in the repository. Reading through open issues can be a great way to gauge what the project needs help with. 
+Fixing typos and other small documentation issues makes for great, easy-to-create (and review) first pull requests. In fact, if you find that the contributing information isn't detailed enough, that could also be your first contribution!
 
-**If you already have a fix in mind that you want to make:**
+When you edit documentation, you can often make the changes in the GitHub interface online versus needing to clone the repository and work locally.
 
-If you want to fix something you found, such as a typo in the documentation, you first want to see if there is an open issue you could work on directly. If an open issue about the topic doesn't exist, you should create a new GitHub issue that details the problem you found and wish to fix.
 
-**If you are looking to contribute but you aren't sure where to start,** 
+:::{admonition} A real-life first contribution to PyPI
 
-Sometimes, when reading through the project's existing issues, you will find something you might be interested in tackling. If that is the case, you can add a message to the open issue you are interested in, stating that you'd like to work on it. 
-
-When scanning the issues, look for ones tagged "good first issue". Or "beginner friendly". Not all maintainers will tag issues but if you see such tags, you know you are in a repository that welcomes new contributions.
+[Here is an example issue that resulted in 2 small pull requests to PyPI (warehouse)](https://github.com/pypi/warehouse/issues/17374). In this case, the images were outdated, so it was a bug in the documentation that needed to be fixed. However, while getting to know the repository, the author also found issues with the development documentation, so they submitted a pull request to address that as well. Both pull requests were small. 
+:::