You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: github-git/first-issue-contribution.md
+49-27Lines changed: 49 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,10 +30,10 @@ what's missing
30
30
31
31
After completing this tutorial, you will be able to:
32
32
33
-
*list the steps involved in contributing to an open source project
34
-
*list the ways you can get to know a repository better before contributing
35
-
*create a fork of a repository that you want to contribute to
36
-
*make a small contribution to a repository through a pull request on GitHub.
33
+
*List the steps involved in contributing to an open source project
34
+
*List the ways you can get to know a repository better before contributing
35
+
*Create a fork of a repository that you want to contribute to
36
+
*Make a small contribution to a sample repository through a GitHub pull request.
37
37
38
38
:::
39
39
@@ -43,73 +43,74 @@ Whether this is your first time contributing to open source, or your 10th, makin
43
43
* You might feel uncertain about your technical git and GitHub skills (imposter syndrome is real!)
44
44
* You might not be sure where to start.
45
45
46
-
In this lesson, you will learn how to start contributing to open source. The upcoming lessons will walk you through not only the technical elements associated with contributing to open source but also the social elements that are good to understand.
46
+
This lessonwill teach you how to start contributing to open source. 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, easier and in some cases it will even ensure your issue or pull request is completed more efficiently.
47
47
48
48
## 1. Get to know the GitHub repository.
49
49
50
-
The first step in contributing to open source is finding and then getting to know the GitHub repository where the code is stored.
50
+
The first step in contributing to open source is finding and getting to know the GitHub repository where the code is stored.
51
51
52
-
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 actually the best way to learn.
52
+
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.
53
53
54
54
:::{todo}
55
55
56
56
There are two options here.
57
+
57
58
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
58
59
59
60
This approach could be fun as the pyos community here could submit lots of pt's that break things for people to fix :)
60
61
61
62
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.
62
63
:::
63
64
64
-
To begin, you should get to know the repository that you wish to contribute to, better. To do this:
65
+
To begin, you should get to know the repository that you wish to contribute to. To do this:
65
66
66
-
1. Read the contributing guide. In the repository, you should see a **CONTRIBUTING.md** file that tells you more about the types of contributions the project accepts and the workflows it embraces.
67
+
1.**Read the contributing guide**: In the repository, you should see a **CONTRIBUTING.md** file that tells you more about the types of contributions the project accepts and the workflows it embraces.
67
68
68
-
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, and you can often make the changes fully in the GitHub interface online versus needing to clone the repository and work locally.
69
+
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.
69
70
70
-
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!
71
+
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!
71
72
72
-
1. Read through the open issues in the repository. Reading through open issues can be a great way to gage what the project needs help with.
73
+
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.
73
74
74
75
**If you already have a fix in mind that you want to make:**
75
76
76
-
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 that you found and wish to fix.
77
+
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.
77
78
78
79
**If you are looking to contribute but you aren't sure where to start,**
79
80
80
81
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.
81
82
82
-
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, then you know you are in a repository that welcomes new contributions.
83
+
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.
83
84
84
85
85
86
## 2. Open or comment on a GitHub issue
86
87
87
88
Once you've decided what you'd like to work on, you can do one of two things
88
89
89
-
1. If there is already an issue open for the item that you want to work on, you can leave a comment indicating your interest in working on it. That comment might look something like this:
90
+
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:
90
91
91
92
> Hey maintainer team 👋. I'm interested in working on this issue. Is there anything specific that I should consider before getting started?
92
93
93
-
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.
94
+
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.
94
95
95
96
### How to create a new issue
96
97
97
98
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:
98
99
99
100
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.
100
-
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, then link to the documentation page that has the error and be specific about what you'd like to fix, add, or enhance.
101
+
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.
101
102
102
103
:::{todo}
103
-
Link to the stravalib issue that I recently worked on where the reproducible example was missing.
104
+
Link to the stravalib issue I recently worked on where the reproducible example was missing.
104
105
:::
105
106
106
-
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 to them, the easier it is for them to understand what your goal is 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 up front will pay off in the issue moving forward.
107
+
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.
107
108
108
-
3. Be patient. Once you have opened your issue, be patient, as it could take some time for maintainers 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.
109
+
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.
109
110
110
-
It could take a few weeks for someone to get back to you.
111
+
**It could take a few weeks for someone to get back to you.**
111
112
112
-
4. If the maintainers invite you to submit a pull request addressing the issue that you left or commented on, you're good to go. At that point, it's time to
113
+
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:
113
114
114
115
* Fork the repository if you haven't already
115
116
* Make the changes that need to be made in your fork.
@@ -129,18 +130,28 @@ Bad / less descriptive issue title examples are below:
129
130
* Fix formatting
130
131
:::
131
132
132
-
## Activity 1: Create an issue, for a bug that you'd like to fix
133
+
If maintainers don't respond after a few weeks, a gentle nudge is ok. That might look something like this:
134
+
135
+
> 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!
136
+
>
133
137
138
+
:::{todo}
139
+
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.
140
+
141
+
The alternative is to put the activities at the top given people often skim
142
+
:::
134
143
135
-
1. go to the xxx repository on GitHub
136
-
2. Exxplore the documentation and code. YOu will find many items that could be fixed, including spelling errors, typos, and more.
137
-
3. Pick something that you would like to fix, and open an issue that specifies what you'd like to implement.
144
+
## Activity 1: Create an issue for a bug that you'd like to fix
145
+
146
+
1. go to the https://www.github.com/pyopensci/repo-name repository on GitHub
147
+
2. Explore the documentation and code. You will find many items that could be fixed, including spelling errors, typos, and more.
148
+
3. Pick something you would like to fix and open an issue specifying what you'd like to implement.
138
149
4. Wait for someone on the pyOpenSci team to respond to you with next steps!
139
150
140
151
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.
141
152
142
153
:::{note}
143
-
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, build confidence. You can always submit more issues and pull requests later!
154
+
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!
144
155
:::
145
156
146
157
@@ -168,6 +179,17 @@ When you have the go-ahead from someone who owns the repository, you are ready t
168
179
169
180
### 2. Make the changes that you said you would make in the issue opened above
170
181
182
+
After you have forked the repo and received the OK to move forward with your pull request:
183
+
184
+
* Open the file that you want to make changes to in your fork.
185
+
* Make the edits that you want to make to the file
186
+
* Commit the changes that you made to the file. Important: try to use a short descriptive commit message that describes what you have changed:
187
+
*
188
+
> fix: fixed numerous typos in the filename.py file
189
+
> fix: updated the code to align with PEP 8 syntax
190
+
> fix: fixed typo in docstring text
191
+
192
+
171
193
:::{todo}
172
194
It might be cool to show first contributions like my first on to nbconvert could be interesting? Other people might have examples too
Copy file name to clipboardExpand all lines: github-git/intro.md
+11-3Lines changed: 11 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -75,7 +75,7 @@ Caption here
75
75
76
76
## What's next
77
77
78
-
In this lesson series, you will learn how to work collaboratively using GitHub. The lessons will combine the technical elements that you need to use git and GitHub with the social dynamics that are not often taught.
78
+
In this lesson series, you will learn how to work collaboratively using GitHub. The lessons will combine the technical elements you need to use git and GitHub with the social dynamics that are not often taught.
0 commit comments