Skip to content

Commit bc33e79

Browse files
lwasserlwasser
committed
Fix: reorganize flow of lessons
1 parent 9511ba8 commit bc33e79

File tree

10 files changed

+410
-330
lines changed

10 files changed

+410
-330
lines changed

‎conf.py‎

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@
5858
"sphinxext.opengraph",
5959
"sphinx_favicon",
6060
"sphinx.ext.todo",
61-
"sphinx_codeautolink",
61+
#"sphinx_codeautolink",
6262
"sphinx.ext.todo",
6363
]
6464

@@ -182,27 +182,28 @@
182182
# ------------------
183183
# Intersphinx & code linking
184184

185-
intersphinx_mapping = {
186-
"python": ("https://docs.python.org/3", None),
187-
"numpy": ("https://numpy.org/doc/stable/", None),
188-
"pandas": ('https://pandas.pydata.org/docs/', None),
189-
"earthpy": ("https://earthpy.readthedocs.io/en/latest/", None),
190-
"matplotlib": ('https://matplotlib.org/stable/', None),
191-
}
192-
193-
codeautolink_global_preface = """
194-
import numpy as np
195-
import pandas as pd
196-
import os
197-
"""
198-
codeautolink_concat_default=True
199-
200-
# suppress all codeautolink warnings, we don't really care if it's busted
201-
suppress_warnings = [
202-
"codeautolink.clean_block",
203-
"codeautolink.parse_block",
204-
"codeautolink.import_star",
205-
"codeautolink.match_block",
206-
"codeautolink.match_name",
207-
"codeautolink.failed_resolve",
208-
]
185+
# intersphinx_mapping = {
186+
# "python": ("https://docs.python.org/3", None),
187+
# "numpy": ("https://numpy.org/doc/stable/", None),
188+
# "pandas": ('https://pandas.pydata.org/docs/', None),
189+
# "earthpy": ("https://earthpy.readthedocs.io/en/latest/", None),
190+
# "matplotlib": ('https://matplotlib.org/stable/', None),
191+
# }
192+
193+
# codeautolink_global_preface = """
194+
# import numpy as np
195+
# import pandas as pd
196+
# import os
197+
# """
198+
# codeautolink_concat_default=True
199+
200+
201+
# # suppress all codeautolink warnings, we don't really care if it's busted
202+
# suppress_warnings = [
203+
# "codeautolink.clean_block",
204+
# "codeautolink.parse_block",
205+
# "codeautolink.import_star",
206+
# "codeautolink.match_block",
207+
# "codeautolink.match_name",
208+
# "codeautolink.failed_resolve",
209+
# ]

‎github-git/0-first-contribution.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
jupytext:
3+
text_representation:
4+
extension: .md
5+
format_name: myst
6+
format_version: 0.13
7+
jupytext_version: 1.16.4
8+
kernelspec:
9+
display_name: Python 3 (ipykernel)
10+
language: python
11+
name: python3
12+
---
13+
14+
(first-contribution)=
15+
# Make Your First Open Source Contribution
16+
17+
🚧 These lessons are under heavy construction and will continue to change through March 2025 🚧
18+
19+
:::{todo}
20+
21+
what's missing
22+
* Create a new branch to work on in your fork -- don't make a pr from your main or master branch
23+
* Closes or addresses #issue number
24+
:::
25+
26+
27+
:::{admonition} What you will learn
28+
29+
After completing this tutorial, you will be able to:
30+
31+
* List the steps involved in contributing to an open source project
32+
* List the ways you can get to know a repository better before contributing
33+
* Create a fork of a repository that you want to contribute to
34+
* Make a small contribution to a sample repository through a GitHub pull request.
35+
36+
:::
37+
38+
Whether this is your first time contributing to open source, or your 10th, making contributions can be anxiety-inducing.
39+
40+
* You might not know the people maintaining the project
41+
* You might feel uncertain about your technical git and GitHub skills (imposter syndrome is real!)
42+
* You might not be sure where to start.
43+
44+
This lesson will teach you how to use GitHub collaboratively so you can start contributing to open source (and working collaboratively on code) . The upcoming lessons will walk you through the technical elements associated with contributing to open source and the social elements that will make your contribution workflow more positive, and, in some cases, it will even ensure your issue or pull request is completed more efficiently.
45+
46+
47+
## GitHub Workflow Summary
48+
49+
The full contribution workflow using only GitHub looks something like this:
50+
51+
* [Get to know the repo that you want to contribute to](get-to-know-repo)
52+
* [Identify an issue or bug that you wish to work on](identify-issue)
53+
* `Fork` the repository you'd like to contribute to.
54+
* OPTIONAL: 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.
55+
* Create a new branch to work on
56+
* 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!
57+
* Commit the changes to your fork.
58+
* Open a <kbd>Pull Request</kbd> to the parent repository, which for this lesson is: `pyopensci/repo-name`. 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!
59+
* 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!
60+
61+
62+
63+
## Activity: Fork a repository and modify a file
64+
65+
### 1. Fork the pyOpenSci practice GitHub repository
66+
67+
Fork the <a href="http://www.github.com/pyopensci/repo-here" target="_blank">pyOpenSci demo repository on GitHub</a>. Remember that a fork is a copy of a repository that is owned by someone else or an organization that lives in your GitHub account.
68+
69+
:::{todo}
70+
Create an animated gif showing how to fork a repo
71+
:::
72+
73+
74+
:::{tip}
75+
A repository fork is a copy of the GitHub repository that you own in your GitHub account. The repository, however, is still connected to the main repository on GitHub that you forked. This connection means that you can submit pull requests and changes to the repository using your fork.
76+
:::
77+
78+
Once you have submitted your issue with the proposed changes, one of the package developers will review the issue and either:
79+
80+
* Suggest changes to your proposed edits or
81+
* Encourage you to submit a pull request with the two identified changes.
82+
83+
When you have the go-ahead from someone who owns the repository, you are ready to create and submit a pull request with your changes.
84+
85+
### 2. Make the changes that you said you would make in the issue opened above
86+
87+
After you have forked the repo and received the OK to move forward with your pull request:
88+
89+
* Open the file that you want to make changes to in your fork.
90+
* Make the edits that you want to make to the file
91+
* Commit the changes that you made to the file. Important: try to use a short descriptive commit message that describes what you have changed:
92+
*
93+
> fix: fixed numerous typos in the filename.py file
94+
> fix: updated the code to align with PEP 8 syntax
95+
> fix: fixed typo in docstring text
96+
97+
98+
:::{todo}
99+
It might be cool to show first contributions like my first on to nbconvert could be interesting? Other people might have examples too
100+
:::
101+
102+
### 3. Create a GitHub pull request (PR)
103+
104+
More here....

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

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
jupytext:
3+
text_representation:
4+
extension: .md
5+
format_name: myst
6+
format_version: 0.13
7+
jupytext_version: 1.16.4
8+
kernelspec:
9+
display_name: Python 3 (ipykernel)
10+
language: python
11+
name: python3
12+
---
13+
14+
(get-to-know-repo)=
15+
# Get to Know a (new to you) GitHub Repository
16+
17+
The first step in contributing to open source is finding and getting to know the GitHub repository where the code is stored.
18+
19+
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.
20+
21+
You will [use this repository](https://github.com/pyOpenSci/pyos-demo-package-contribute) as a place where you can practice for all of these lessons.
22+
23+
:::{todo}
24+
25+
There are two options here.
26+
27+
1. create a sample pyospackage repo with docs with many typos everywhere for people to fix. The downside is that it doesn't scale unless we have a reset repo action (which we could do) that essentially replaces the typos every few months. But this is likely the best option for actual practice on a (semi-real) code base
28+
29+
This approach could be fun as the pyos community here could submit lots of pt's that break things for people to fix :)
30+
31+
2. Create a repo that people add a file to (like hometowns) with info about a town they like. This approach scales forever and ever and has worked well in the past. It's more focused on the fork, create something, pull request workflow without the open source flavor. It might be less interesting than a package where we could have bugs, typos, and other things for people to fix.
32+
:::
33+
34+
## Get started
35+
36+
To begin, you should get to know the repository that you want to contribute to. To do this:
37+
38+
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.
39+
40+
41+
:::{figure} /images/github/use-github-yourself.png
42+
:alt: Alt here
43+
44+
Add screenshot of the GitHub repo with the contributing file highlighted
45+
:::
46+
47+
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.
48+
49+
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!
50+
51+
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.
52+
53+
**If you already have a fix in mind that you want to make:**
54+
55+
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.
56+
57+
**If you are looking to contribute but you aren't sure where to start,**
58+
59+
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.
60+
61+
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.

‎github-git/2-identify-issue.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
jupytext:
3+
text_representation:
4+
extension: .md
5+
format_name: myst
6+
format_version: 0.13
7+
jupytext_version: 1.16.4
8+
kernelspec:
9+
display_name: Python 3 (ipykernel)
10+
language: python
11+
name: python3
12+
---
13+
14+
(identify-issue)=
15+
# Identify an issue to work on
16+
17+
Your first step is to identify an issue that you wish to work on
18+
19+
## 2. Open or comment on a GitHub issue
20+
21+
Once you've decided what you'd like to work on, you can do one of two things
22+
23+
1. If an issue is already open for the item you want to work on, you can leave a comment indicating your interest in working on it. That comment might look something like this:
24+
25+
> Hey maintainer team 👋. I'm interested in working on this issue. Is there anything specific that I should consider before getting started?
26+
27+
Leaving a comment in a new-to-you repository might feel scary, but don't worry. If you communicate in a respectful way, then it's likely that you will also get a nice response in return. Also, if you don't get a supportive response, there are other projects you could work on that may be a better fit. Not all projects are open to new contributions. And that is OK, too.
28+
29+
### How to create a new issue
30+
31+
If the issue isn't already open, you can create a new issue describing what you'd like to work on. What is most important when creating a new issue is:
32+
33+
1. Ensure the issue has a **carefully crafted title** that describes what you want to fix. Some packages have issue templates that you can fill out. Other projects may not have templates set up.
34+
2. Be **specific about what you'd like to fix** in the issue. If it's a bug that you are fixing in the code, provide a **fully reproducible code example** of how to trigger the bug so the maintainers can easily understand the problem. If it is a documentation fix, link to the documentation page with the error and be specific about what you'd like to fix, add, or enhance.
35+
36+
:::{todo}
37+
Link to the stravalib issue I recently worked on where the reproducible example was missing.
38+
:::
39+
40+
The content of your issue is more important than you might think. Maintainers are often volunteers, working on projects in their free time. The more information you can provide them, the easier it is for them to understand your goal and how to support you. Be as specific as you can be in your issue! This might mean that it takes you some time to create the issue. The time invested upfront will pay off the issue moving forward.
41+
42+
3. **Be patient**: Once you have opened your issue, be patient, as maintainers could take some time to respond. The timeline will vary based on how active the repository issue is, how many open issues there are, the size of the maintainer team, and even what's going on in the maintainer's life at that particular time.
43+
44+
**It could take a few weeks for someone to get back to you.**
45+
46+
4. If the maintainers invite you to submit a pull request addressing the issue you left or commented on, you're good to go. At that point, it's time to:
47+
48+
* Fork the repository if you haven't already
49+
* Make the changes that need to be made in your fork.
50+
* Open up a pull request to address those changes.
51+
52+
:::{tip}
53+
Make your GitHub issue title specific enough that people can tell what the issue is about without reading all the details. This makes it easier to identify potentially overlapping issues quickly.
54+
A few good issue titles are below:
55+
56+
* Add: update docstring in the `function_name_here()` function.
57+
* Update the module_name.py module with a more clear module docstring
58+
* Fix: Typo in the documentation page for doc-page-here
59+
* Fix: Bug in xxx module that causes x, y, z to happen
60+
61+
Bad / less descriptive issue title examples are below:
62+
* Update documentation.
63+
* Fix formatting
64+
:::
65+
66+
If maintainers don't respond after a few weeks, a gentle nudge is ok. That might look something like this:
67+
68+
> Hey, maintainer team 👋. I'm just following up to see if you have any feedback on my issue here to fix ___add brief description here__. Please let me know if you would like me to move forward with a pull request or if you have any feedback or concerns about the issue!
69+
>
70+
71+
:::{todo}
72+
It may make sense to have the activities in a separate file. And to refer to the pages they should review before starting each activity.
73+
74+
The alternative is to put the activities at the top given people often skim
75+
:::
76+
77+
## Activity 1: Create an issue for a bug that you'd like to fix
78+
79+
1. go to the https://www.github.com/pyopensci/repo-name repository on GitHub
80+
2. Explore the documentation and code. You will find many items that could be fixed, including spelling errors, typos, and more.
81+
3. Pick something you would like to fix and open an issue specifying what you'd like to implement.
82+
4. Wait for someone on the pyOpenSci team to respond to you with next steps!
83+
84+
Once you have submitted an issue and a developer from the package you are submitting to (in this case, the pyOpenSci team) agrees to your proposed changes, you are ready to implement these changes locally on your computer and submit a pull request.
85+
86+
:::{note}
87+
For this activity, focus on the process of contributing and making a small change to a single file; you don't need to make a huge change or fix everything in a file. Most first contributions are small updates to documentation. Start there and build confidence. You can always submit more issues and pull requests later!
88+
:::

‎github-git/3-fork-repo.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
jupytext:
3+
text_representation:
4+
extension: .md
5+
format_name: myst
6+
format_version: 0.13
7+
jupytext_version: 1.16.4
8+
kernelspec:
9+
display_name: Python 3 (ipykernel)
10+
language: python
11+
name: python3
12+
---
13+
14+
# How to Fork a GitHub Repository
15+
16+
🚧 These lessons are under heavy construction and will continue to change through March 2025 🚧
17+
18+
:::{admonition} What you will learn:
19+
20+
* Explain how a **GitHub** repository stores and tracks changes to files.
21+
* Create a copy of (<kbd>fork</kbd>) other users' files on **GitHub.com**.
22+
* Use the `git clone` command to download a copy of a **GitHub** repository to your computer.
23+
:::
24+
25+
26+
## Who owns a GitHub repository?
27+
28+
When a repository is stored on **GitHub.com**, it is assigned a unique URL (i.e. link on the **GitHub.com** website) that can be used to find the repository and access its files. While repositories on **GitHub.com** can be made either public or private, the default is public for free **GitHub** accounts.
29+
30+
In either case (public or private), the URL links to a **GitHub** repository always follows the same format:
31+
32+
`https://github.com/username/repository-name`
33+
34+
The username is the username owner of the repo owner. The username can either be an individual such as `lwasser` (your **GitHub** username), or it can represent an organization such as `pyOpenSci`.
35+
36+
For example, the repository that you will work within this lesson is owned by `pyopensci.` Therefore, the URL looks like this:
37+
38+
`https://github.com/pyopensci/repo-name`
39+
40+
(fork-repo)=
41+
## Fork a GitHub repository
42+
43+
Using **GitHub.com**, you can create a copy of another user's or organization’s repository—a process called `forking`. When you fork a repository, you get your own version to work on. And you can do that wrok without affecting the original files in the parent repository. Others can also fork your repositories, creating their own copies.
44+
45+
Forking is useful because the fork remains linked to the original repository. This allows you to:
46+
- Update your fork with changes from the original repository.
47+
- Suggest changes to the original repository, which the owner can review and accept.
48+
49+
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**.
50+
51+
To fork a repo:
52+
53+
1. Navigate to the repo page that you wish to fork - example:
54+
55+
`https://github.com/pyopensci/repo-name`
56+
57+
2. On that page, you will see a button in the UPPER RIGHT hand corner that says `Fork`. The number next to that button tells you how many times the repo has already been forked.
58+
3. Click on the `Fork` button and select your user account when it asks you where you want to fork the repo.
59+
4. Once you have forked the repo, you will have a copy in your account. Navigate to your repo page. The URL should look something like this:
60+
61+
`https://github.com/your-user-name/repo-name`
62+
63+
:::{figure} /images/github/image-coming-soon.png
64+
:alt: alt text here
65+
66+
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.
67+
:::

0 commit comments

Comments
 (0)