Skip to content

Commit 388e57b

Browse files
lwasserlwasser
committed
fix: pr page plus screencasts
1 parent cdcde3e commit 388e57b

13 files changed

+286
-23
lines changed

‎conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222

2323
# -- Project information -----------------------------------------------------
2424

25-
project = "pyOpenSci Python Package Guide"
25+
project = "pyOpenSci Open Source Lessons"
2626
copyright = f"{current_year}, {organization_name}"
2727
author = "pyOpenSci Community"
2828
# Version is needed to avoid "cant describe anything fatal error"

‎github-git/4-edit-commit-files.md‎

Lines changed: 31 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -13,25 +13,35 @@ kernelspec:
1313

1414
# Your first edits to a file in your fork
1515

16-
In the previous lesson, [you identified something that you wanted to fix in our example GitHub repository](3-identify-issue). Ideally, the fix that you identified is small, text-based, and can be made by modifying a single file.
16+
:::{todo}
17+
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.
18+
19+
So I think we want to break this down into two things
1720

18-
After you [forked the repository that you want to contribute to](3-fork-repo) and received approval from a maintainer to work on the issue, it's time to move forward with a pull request!
21+
1. The drive-by pull request
22+
* Click on the edit button in the repo that you want to make changes.
23+
* If you don't have permissions, it will automatically ask you about making a branch, which will be from your fork.
24+
25+
2. The pr from your fork. If the fork already exists, then you can still edit the file in place.
26+
27+
:::
28+
29+
In the previous lesson, [you identified something that you wanted to fix in our example GitHub repository](2-identify-issue). Ideally, the fix that you identified is small, text-based, and can be made by modifying a single file.
30+
31+
After you [forked the repository that you want to contribute to](3-fork-repo) and received approval from a maintainer to work on the issue, it's time to start making the changes you suggested.
1932

2033
:::{admonition} What you'll learn here
2134
:class: tip
2235
In this lesson, you will edit a file in the demo pyOpenSci repository using the GitHub interface in your [forked repo](3-fork-repo). You will then commit your changes.
23-
2436
:::
2537

2638

2739
Here, you will make the changes that you proposed to work on using only the native GitHub interface.
28-
You do not need to [clone or make a copy of your repo locally](clone-repo) to do this!
40+
To do this, you do not need to [clone or make a copy of your repo locally](clone-repo).
2941

3042

3143
:::{admonition} Activity: Make a change to a file and commit it to your fork
3244

33-
It's time to make the changes to a file in your fork that you proposed in the open issue:
34-
3545
1. Navigate to your fork on GitHub.com
3646
2. In the GitHub interface, click on the file that you proposed to modify or fix [in the identify issue lesson](2-identify-issue): instructions on how to do this are below
3747
3. Click on the edit <kbd><i class="fa-solid fa-pencil"></i></kbd> button in the GitHub interface.
@@ -46,7 +56,10 @@ Some examples:
4656
>
4757
> fix: fixed typo in docstring text
4858
49-
*An overview of all of these steps is below.*
59+
:::
60+
61+
:::{figure} /images/github/edit-commit-file.gif
62+
5063
:::
5164

5265

@@ -56,20 +69,20 @@ Editing a file on GitHub allows you to focus on the contributing workflow withou
5669

5770
Following this process, you can edit as many files as you wish. However, on GitHub, you must edit and commit changes to them individually.
5871

59-
### How to edit a file on GitHub
60-
61-
TODO: add a screen capture of opening and editing a file.
72+
### Editing files on GitHub vs GitHub Codespaces vs Locally
6273

74+
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
6375

76+
1. use the command line to edit the file
77+
2. know how to use .git
6478

65-
:::{admonition} GitHub Codespaces Provide Online GitHub Development Environments
79+
However, the one small downside of this approach is that you can only edit and commit one file at a time.
6680

67-
GitHub Codespaces are cloud development environments that can be created and used on GitHub.
81+
An alternative way to edit multiple files on GitHub is to use GitHub Codespaces.
6882

69-
Projects may sometimes offer [GitHub codespaces](github-codespaces), which allows you to edit multiple files and commit them together. You can also create a CodeSpace yourself in your fork!
83+
[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.
7084

71-
GitHub Codespaces allows you to work on content in a cloud-based coding environment using an interface like VSCode fully in your browser. If set up correctly, they can contain a project's development environment.
72-
:::
85+
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.
7386

7487
## What is a commit?
7588

@@ -80,7 +93,7 @@ Here are 3 points to remember when you think about commits:
8093
2. Each commit that you make represents a set of changes to one or more files in your repository at a specific time.
8194

8295
:::{figure} /images/github/git-commits-files.png
83-
: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 also highlighted in green, along with the commit message, “Fix: copy edits.” At the bottom, a comparison shows the document after each commit, illustrating how the file evolves with changes.
96+
: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.
8497

8598
:::
8699

@@ -92,6 +105,8 @@ Here are 3 points to remember when you think about commits:
92105

93106
:::
94107

108+
## Up next - create a pull request
109+
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](5-pull-request). You will learn how to do that next.
95110

96111
:::{todo}
97112
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-git/5-pull-request.md‎

Lines changed: 188 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,191 @@ kernelspec:
1111
name: python3
1212
---
1313

14-
# Submit a Pull Request
14+
```{raw-cell}
15+
16+
---
17+
title: "Contribute to Open Source: How to Submit a Pull request"
18+
description: "A description here"
19+
keywords: python, open source, tutorial
20+
---
21+
```
22+
23+
# How to Submit a GitHub Pull Request
24+
25+
In the last lesson, you learned how to [make and commit a change to a document in a GitHub repository](4-edit-commit-files).
26+
In this lesson, you will learn how to submit a pull request after making changes to a file in a GitHub repository.
27+
28+
A GitHub pull request (**PR**):
29+
30+
1. **Allows you to suggest changes rather than making them directly to a repo you don't own** in a transparent way. You can't break things by submitting a PR!
31+
1. **Supports Review**: A pull request also triggers a review process where other repository owners and users can review and comment on your changes and suggest edits to your changes line-by-line.
32+
1. **Maintainers to manage contributions**: PRs allow maintainers to document, approve, and merge contributions into the project in a consistent way.
33+
34+
Pull requests empower you to contribute to the work of others in an open and accessible way, even if you don't have direct access to the repository.
35+
36+
:::{admonition} Activity: Submit a PR to the pyOS parent repository
37+
38+
Using the branch that you created in the previous lesson, create a pull request for the pyOS parent repository.
39+
:::
40+
41+
## Step 1: Open your GitHub pull request
42+
43+
To start a PR, click the <kbd>`New pull request`</kbd> button on the main page of your forked repository. Or, if you recently made a change to a branch in your fork, then GitHub will recognize is and prompt you to submit a PR (see the image below).
44+
45+
46+
:::{figure} /images/github/create-pr-fork.gif
47+
48+
When you edit a file in your fork, GitHub recognizes it and prompts you to create a pull request.
49+
:::
50+
51+
52+
:::{tip}
53+
You will notice the Pull Request button in different places in the GitHub interface. Note that even tho you see the button on different pages, it does the same thing.
54+
:::
55+
56+
57+
### Step 2: Setup your pull request targets (head and base)
58+
59+
When you create your pull request, take note of the head and base targets.
60+
The repo that you wish to update is the base repo) and the
61+
repo that contains the content that you want to use to update the base
62+
(the head repo).
63+
64+
In this example, you want to update:
65+
66+
* **base**: `pyopensci/pyos-demo-package-contribute` with
67+
* **head**: commits in your fork `your-username/pyos-demo-package-contribute`.
68+
69+
The above pull request configuration tells **GitHub** to update the base repository with contents from your forked repository or the head repository.
70+
71+
72+
:::{admonition} Pull request terminology: Head vs. Base
73+
74+
When submitting a pull request, you specify two repositories:
75+
76+
- **Base**: The repository you want to update (e.g., your colleague's repo).
77+
- **Head**: The repository with the changes to be added (e.g., your fork).
78+
79+
The **head** is a**head** of the **base**, meaning the head repo has changes that the base repo doesn't yet have. The goal is to merge changes from the **head** (your fork) into the **base** (your colleague's repo).
80+
81+
When you create a pull request, GitHub will auto-fill these fields. For example:
82+
- **Base fork**: `colleague-username/project-name`
83+
- **Head fork**: `your-username/project-name`
84+
:::
85+
86+
### Step 3 - Verify The Changes In Your Pull Request
87+
88+
When you compare two repos in a pull request page, **GitHub** provides an overview of the differences (diffs) between the files.
89+
90+
Carefully review these changes to
91+
ensure that the changes that you are submitting are in fact the ones that you
92+
want to submit.
93+
94+
1. First, look at the number of files. How many files did you modify? Do you see that many files listed in the **PR**?
95+
2. Look over the changes made to each file. Do the changes all look correct (likechanges that you committed to the repository)?
96+
97+
:::{figure} /images/github/pr-check-files.gif
98+
99+
When you first create a PR, be sure to check the PR contents. Notice that the number of files and commits are displayed in this image. Make sure these numbers make sense based upon the changes that you made.
100+
:::
101+
102+
<i class="fa fa-star"></i> **Data Tip:** You can also click on the commit titles to see the specific changes in each commit. This is another way to check that the contents of a PR are what you expect them to be.
103+
{: .notice--success}
104+
105+
This review of your own **PR** before submitting it is important. Remember that someone
106+
else is going to take time to review your PR.
107+
108+
Make sure that you take care of
109+
cleaning up what you can FIRST, before submitting the PR.
110+
111+
### Step 4 - Click on the Create New Pull Request Button
112+
113+
The next step of the create PR process is to click the "Create Pull Request" button. Note that this button will NOT be available if you have not changed your repo (e.g. fork).
114+
115+
Click the green “Create Pull Request” button to start your pull request. Once you do that, a title box and description box will be visible.
116+
117+
Add a title and write a brief description of your changes. When you have added your
118+
title and description, click on “Create Pull Request”.
119+
120+
:::{tip}
121+
You can modify the title and description of your pull request at any time - even after you've submitted the pull request!
122+
:::
123+
124+
Pull request titles should be concise and descriptive of the content in the pull request. More detailed notes can be left in the comments box.
125+
126+
127+
128+
## Pull Requests and Your Location On GitHub
129+
130+
When you create a new pull request, you will be automatically transferred to the
131+
**GitHub.com** URL or landing page for the base repository (your colleague's
132+
repository).
133+
134+
At this point, you have submitted your pull request!
135+
136+
At the bottom of your pull request, you may see an large green button that says
137+
**Merge Pull Request**. This button will be used by owner of the
138+
repository (your colleague or perhaps others working on this collaborative project)
139+
to merge in your changes, when a review has been completed.
140+
141+
The repo owner will
142+
review your PR and may ask for changes. When they are happy with all of the changes, your PR could get merged!
143+
144+
<i class="fa fa-star"></i> **Data Tip:** All future commits that you make to your fork (on the branch where you are working) will continue to be added to the open pull request UNTIL it is merged.
145+
{: .notice--success}
146+
147+
## How To Merge GitHub Pull Requests on GitHub
148+
149+
After you have submitted your PR, someone who owns or manages the repo where you
150+
are submitting the PR will review it. At this point, they will either:
151+
152+
1. suggest that you make some changes to the PR or
153+
2. merge the PR if they are happy with all of the changes that you made.
154+
155+
:::{todo}
156+
A screencast showing how this process works is below.
157+
158+
It's common for a reviewer to comment on your pull request and request changes. Once the reviewer is happy with the PR, they will merge it using the merge button on the bottom of the PR. It is important to note that you can only merge a PR in a repo in which you have permission to merge.
159+
:::
160+
161+
## Pull Requests and Your Location On GitHub
162+
163+
When you create a new pull request, you will be automatically transferred to the
164+
**GitHub.com** URL or landing page for the base repository (your colleague's
165+
repository).
166+
167+
At this point, you have submitted your pull request!
168+
169+
At the bottom of your pull request, you may see an large green button that says
170+
**Merge Pull Request**. This button will be used by owner of the
171+
repository (your colleague or perhaps others working on this collaborative project)
172+
to merge in your changes, when a review has been completed.
173+
174+
The repo owner will
175+
review your PR and may ask for changes. When they are happy with all of the changes, your PR could get merged!
176+
177+
<i class="fa fa-star"></i> **Data Tip:** All future commits that you make to your fork (on the branch where you are working) will continue to be added to the open pull request UNTIL it is merged.
178+
{: .notice--success}
179+
180+
## How To Merge GitHub Pull Requests on GitHub
181+
182+
After you have submitted your PR, someone who owns or manages the repo where you
183+
are submitting the PR will review it. At this point, they will either:
184+
185+
1. suggest that you make some changes to the PR or
186+
2. merge the PR if they are happy with all of the changes that you made.
187+
188+
189+
190+
### How To Close Pull Requests on GitHub
191+
192+
You can also close a pull request on **GitHub** if you decide you are not
193+
ready to submit your files from your forked repository to the original repository.
194+
195+
For example, the pull request you just created in this lesson can be closed anytime before it is merged.
196+
197+
When you are ready to submit changes,
198+
you can simply create a new pull request on **GitHub** following these same steps.
199+
200+
To close a pull request, click on `Close pull request` button towards the
201+
bottom of the pull request page.

‎github-git/intro.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -75,11 +75,12 @@ https://www.youtube.com/watch?v=eWxxfttcMts
7575
:hidden:
7676

7777
0. Your contributing path <0-first-contribution>
78-
1. Get to know the repo <1-get-to-know-repo>
79-
2. Find an issue <2-identify-issue>
80-
3. Fork GitHub Repo <3-fork-repo>
81-
4. Edit & commit files <4-edit-commit-files>
82-
5. Submit Pull Request <5-pull-request>
78+
1. Ways to contribute <ways-to-contribute>
79+
2. Get to know the repo <1-get-to-know-repo>
80+
3. Find an issue <2-identify-issue>
81+
4. Fork GitHub Repo <3-fork-repo>
82+
5. Edit & commit files <4-edit-commit-files>
83+
6. Submit Pull Request <5-pull-request>
8384

8485
:::
8586

‎github-git/ways-to-contribute.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
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+
```{raw-cell}
15+
16+
---
17+
title: TITLE
18+
description: A long time ago
19+
---
20+
```
21+
22+
23+
24+
25+
26+
# Ways to contribute
27+
28+
There are several ways to contribute to open source if you are just getting started. This page overviews them and then links to more information about the various steps.
29+
30+
## Start here if you haven't yet forked the repository
31+
32+
If you don't already have a fork of the repo that you wish to contribute to in your GitHub account, and you have already opened an issue for the item that you want to fix, you can start by going to GitHub, clicking on the edit button of the file that you want to edit, in the repository that you want to work on (in this case pyopensci/pyos-package-contribute). Do the following:
33+
34+
If you haven't already forked the repository, then GitHub will do the following:
35+
36+
1. Go to [https://github.com/pyOpenSci/pyos-demo-package-contribute](https://github.com/pyOpenSci/pyos-demo-package-contribute)
37+
2. Navigate to the file that you wish to edit. Click on the <kbd><i class="fa-solid fa-pencil"></i></kbd> edit button.
38+
3. Given that you haven't forked the repo yet, GitHub will inform you that you need to create a fork first.
39+
4. Once your fork has been created, you can edit the file in the GitHub interface. Note that you are working on your fork of the repo, not the copy that pyOpenSci owns
40+
1. Once you are happy with the changes, you can commit them to version control. In this case you will click on the "propose changes button" to commit your changes.
41+
7. Once you have committed the file (or hit the proposed changes button), GitHub will open a pull request for you in the parent repository.
42+
43+
:::{figure} /images/github/contribute-no-fork.gif
44+
The GitHub contribute workflow for someone who hasn't yet created a fork of the repo that they wish to contribute to.
45+
:::
46+
47+
::::{tip}
48+
49+
If you already have a fork of the repo, when you click on the edit file in the pyOpenSci repo, it will tell you that you will edit the file in your fork. Be careful with this approach, however, because GitHub defaults to editing the file on your main branch.
50+
51+
:::{figure} /images/github/edit-file-github-fork.png
52+
Don't do this!
53+
:::
54+
55+
If you already have a fork, we suggest that you edit the file directly from your fork
56+
57+
:::{figure} /images/github/edit-file-github-fork.png
58+
Edit from your fork directly instead so you can make a new branch.
59+
:::
60+
::::

‎images/github/contribute-no-fork.gif‎

3.43 MB
Loading

‎images/github/create-pr-fork.gif‎

1.15 MB
Loading

‎images/github/edit-commit-file.gif‎

7.65 MB
Loading

‎images/github/edit-file-github-fork.png‎

607 KB
Loading

‎images/github/edit-file-new-branch.gif‎

2.99 MB
Loading

0 commit comments

Comments
 (0)