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/0-first-contribution.md
+23-57Lines changed: 23 additions & 57 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,76 +29,42 @@ what's missing
29
29
After completing this tutorial, you will be able to:
30
30
31
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
32
33
+
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.
36
34
:::
37
35
38
-
Whether this is your first time contributing to open source, or your 10th, making contributions can be anxiety-inducing.
36
+
Contributing to open source software can feel intimidating.
39
37
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.
38
+
* You may not know the project maintainers.
39
+
* You might feel unsure about your Git and GitHub skills (imposter syndrome is real!).
40
+
* You may not know where to begin.
43
41
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.
42
+
This lesson series will teach you how to collaborate using GitHub, helping you confidently contribute to open source repositories and collaborate with colleagues.
45
43
44
+
## GitHub workflow summary
46
45
47
-
##GitHub Workflow Summary
46
+
The GitHub contribution workflow looks something like this:
48
47
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 <ahref="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
-
:::
48
+
* 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!
49
+
* 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).
50
+
* 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.
51
+
* 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.
72
52
73
53
74
54
:::{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.
55
+
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.
76
56
:::
77
57
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
58
:::{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
-
:::
59
+
The section below needs work and to be fleshed out. PR page doesn't exist yet.
60
+
:::
61
+
62
+
* Create a new branch to work on
63
+
* 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!
64
+
* Commit the changes to your fork.
65
+
* 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!
66
+
* 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!
101
67
102
-
### 3. Create a GitHub pull request (PR)
68
+
##Your first step: Get to know the repo
103
69
104
-
More here....
70
+
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)
Copy file name to clipboardExpand all lines: github-git/1-get-to-know-repo.md
+7-14Lines changed: 7 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,34 +14,27 @@ kernelspec:
14
14
(get-to-know-repo)=
15
15
# Get to Know a (new to you) GitHub Repository
16
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}
17
+
:::{admonition} What you will learn:
24
18
25
-
There are two options here.
19
+
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.
26
20
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
21
+
:::
28
22
29
-
This approach could be fun as the pyos community here could submit lots of pt's that break things for people to fix :)
23
+
The first step in contributing to open source is finding and getting to know the GitHub repository where the code is stored.
30
24
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
-
:::
25
+
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.
33
26
27
+
(contributing)=
34
28
## Get started
35
29
36
30
To begin, you should get to know the repository that you want to contribute to. To do this:
37
31
38
32
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.
Add screenshot of the GitHub repo with the contributing file highlighted
45
38
:::
46
39
47
40
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.
Copy file name to clipboardExpand all lines: github-git/2-identify-issue.md
+14-1Lines changed: 14 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,19 +26,32 @@ Once you've decided what you'd like to work on, you can do one of two things
26
26
27
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
28
29
+
(create-issue)=
29
30
### How to create a new issue
30
31
31
32
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
33
34
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
+
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 specify what you'd like to fix, add, or enhance.
35
36
36
37
:::{todo}
37
38
Link to the stravalib issue I recently worked on where the reproducible example was missing.
38
39
:::
39
40
40
41
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
43
+
44
+
:::{admonition} Tips for Submitting Issues
45
+
46
+
-**Search First**: Before creating a new issue, check if someone else has already reported it.
47
+
-**Be Clear**: Provide a detailed, reproducible example when reporting bugs.
48
+
-**Be Constructive**: Avoid blaming or harsh criticism. Instead, frame your concerns as suggestions.
49
+
50
+
Example:
51
+
_Not Constructive_: "This feature is broken and useless."
52
+
_Constructive_: "I encountered an issue when using this feature. Here's the error and steps to reproduce it."
53
+
:::
54
+
42
55
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
56
44
57
**It could take a few weeks for someone to get back to you.**
Copy file name to clipboardExpand all lines: github-git/3-fork-repo.md
+49Lines changed: 49 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,6 +11,7 @@ kernelspec:
11
11
name: python3
12
12
---
13
13
14
+
(fork-repository)=
14
15
# How to Fork a GitHub Repository
15
16
16
17
🚧 These lessons are under heavy construction and will continue to change through March 2025 🚧
@@ -65,3 +66,51 @@ To fork a repo:
65
66
66
67
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
68
:::
69
+
70
+
71
+
72
+
## Activity: Fork a repository and modify a file
73
+
74
+
### 1. Fork the pyOpenSci practice GitHub repository
75
+
76
+
Fork the <ahref="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.
77
+
78
+
:::{todo}
79
+
Create an animated gif showing how to fork a repo
80
+
:::
81
+
82
+
83
+
:::{tip}
84
+
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.
85
+
:::
86
+
87
+
Once you have submitted your issue with the proposed changes, one of the package developers will review the issue and either:
88
+
89
+
* Suggest changes to your proposed edits or
90
+
* Encourage you to submit a pull request with the two identified changes.
91
+
92
+
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.
93
+
94
+
95
+
96
+
## Activity: Fork a repository and modify a file
97
+
98
+
### 1. Fork the pyOpenSci practice GitHub repository
99
+
100
+
Fork the <ahref="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.
101
+
102
+
:::{todo}
103
+
Create an animated gif showing how to fork a repo
104
+
:::
105
+
106
+
107
+
:::{tip}
108
+
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.
109
+
:::
110
+
111
+
Once you have submitted your issue with the proposed changes, one of the package developers will review the issue and either:
112
+
113
+
* Suggest changes to your proposed edits or
114
+
* Encourage you to submit a pull request with the two identified changes.
115
+
116
+
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.
In this lesson, you will edit a documentation file (or a docstring) using the GitHub interface. You do not need to [clone or make a copy of your repo locally](clone-repo) to do this! This is a great way to make your first contribution to open source without using the command line!
17
+
18
+
## Make the changes that you said you would make in the issue opened above
19
+
20
+
After you have forked the repo and received the OK to move forward with your pull request:
21
+
22
+
* Open the file you want to change in your fork.
23
+
* Make the edits that you want to make to the file
24
+
* Commit the changes that you made to the file. Important: try to use a short descriptive commit message that describes what you have changed:
25
+
*
26
+
> fix: fixed numerous typos in the filename.py file
27
+
> fix: updated the code to align with PEP 8 syntax
28
+
> fix: fixed typo in docstring text
29
+
30
+
::::{admonition} What is a commit??
31
+
32
+
A **commit** is a feature in the [git version control](what-is-git) that is similar to saving your changes with a note explaining what you did.
33
+
34
+
35
+
36
+
:::{figure} /images/github/git-commits-files.png
37
+
:alt: Alt here
38
+
39
+
:::
40
+
41
+
::::
42
+
43
+
:::{todo}
44
+
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/what-is-git-github.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -35,6 +35,7 @@ Related to open science, GitHub:
35
35
36
36
By combining Git’s version control with GitHub’s collaborative features, you can manage code efficiently while supporting openness, transparency, and truly open collaboration.
37
37
38
+
(what-is-git)=
38
39
## What is git?
39
40
40
41
Git is a powerful **version control system** that enables teams to track, manage, and collaborate on code and documentation changes over time. While it is best known for its use in software development, Git is equally valuable in **open science** and **open source workflows**.
0 commit comments