Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Reorder and organize lessons #99

Merged
merged 2 commits into from
Jan 14, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 23 additions & 57 deletions github-git/0-first-contribution.md
Original file line number Diff line number Diff line change
@@ -29,76 +29,42 @@ what's missing
After completing this tutorial, you will be able to:

* List the steps involved in contributing to an open source project
* List the ways you can get to know a repository better before contributing
* Create a fork of a repository that you want to contribute to
* Make a small contribution to a sample repository through a GitHub pull request.

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.
:::

Whether this is your first time contributing to open source, or your 10th, making contributions can be anxiety-inducing.
Contributing to open source software can feel intimidating.

* You might not know the people maintaining the project
* You might feel uncertain about your technical git and GitHub skills (imposter syndrome is real!)
* You might not be sure where to start.
* 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 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.
This lesson series will teach you how to collaborate using GitHub, helping you confidently contribute to open source repositories and collaborate with colleagues.

## GitHub workflow summary

## GitHub Workflow Summary
The GitHub contribution workflow looks something like this:

The full contribution workflow using only GitHub looks something like this:

* [Get to know the repo that you want to contribute to](get-to-know-repo)
* [Identify an issue or bug that you wish to work on](identify-issue)
* `Fork` the repository you'd like to contribute to.
* 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.
* 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, 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!
* 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!



## Activity: Fork a repository and modify a file

### 1. Fork the pyOpenSci practice GitHub repository

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.

:::{todo}
Create an animated gif showing how to fork a repo
:::
* 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.


:::{tip}
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.
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.
:::

Once you have submitted your issue with the proposed changes, one of the package developers will review the issue and either:

* Suggest changes to your proposed edits or
* Encourage you to submit a pull request with the two identified changes.

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.

### 2. Make the changes that you said you would make in the issue opened above

After you have forked the repo and received the OK to move forward with your pull request:

* Open the file that you want to make changes to in your fork.
* Make the edits that you want to make to the file
* Commit the changes that you made to the file. Important: try to use a short descriptive commit message that describes what you have changed:
*
> fix: fixed numerous typos in the filename.py file
> fix: updated the code to align with PEP 8 syntax
> fix: fixed typo in docstring text


:::{todo}
It might be cool to show first contributions like my first on to nbconvert could be interesting? Other people might have examples too
:::
The section below needs work and to be fleshed out. PR page doesn't exist yet.
:::

* 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!

### 3. Create a GitHub pull request (PR)
## Your first step: Get to know the repo

More here....
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)
21 changes: 7 additions & 14 deletions github-git/1-get-to-know-repo.md
Original file line number Diff line number Diff line change
@@ -14,34 +14,27 @@ kernelspec:
(get-to-know-repo)=
# Get to Know a (new to you) GitHub Repository

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.

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.

:::{todo}
:::{admonition} What you will learn:

There are two options here.
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.

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
:::

This approach could be fun as the pyos community here could submit lots of pt's that break things for people to fix :)
The first step in contributing to open source is finding and getting to know the GitHub repository where the code is stored.

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.
:::
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.


:::{figure} /images/github/use-github-yourself.png
:::{figure} /images/github/github-contributing-file.png
:alt: Alt here

Add screenshot of the GitHub repo with the contributing file highlighted
:::

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.
15 changes: 14 additions & 1 deletion github-git/2-identify-issue.md
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

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.

(create-issue)=
### How to create a new issue

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:

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.
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.
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.

:::{todo}
Link to the stravalib issue I recently worked on where the reproducible example was missing.
:::

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.


:::{admonition} Tips for Submitting Issues

- **Search First**: Before creating a new issue, check if someone else has already reported it.
- **Be Clear**: Provide a detailed, reproducible example when reporting bugs.
- **Be Constructive**: Avoid blaming or harsh criticism. Instead, frame your concerns as suggestions.

Example:
_Not Constructive_: "This feature is broken and useless."
_Constructive_: "I encountered an issue when using this feature. Here's the error and steps to reproduce it."
:::

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.

**It could take a few weeks for someone to get back to you.**
49 changes: 49 additions & 0 deletions github-git/3-fork-repo.md
Original file line number Diff line number Diff line change
@@ -11,6 +11,7 @@ kernelspec:
name: python3
---

(fork-repository)=
# How to Fork a GitHub Repository

🚧 These lessons are under heavy construction and will continue to change through March 2025 🚧
@@ -65,3 +66,51 @@ To fork a repo:

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.
:::



## Activity: Fork a repository and modify a file

### 1. Fork the pyOpenSci practice GitHub repository

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.

:::{todo}
Create an animated gif showing how to fork a repo
:::


:::{tip}
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.
:::

Once you have submitted your issue with the proposed changes, one of the package developers will review the issue and either:

* Suggest changes to your proposed edits or
* Encourage you to submit a pull request with the two identified changes.

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.



## Activity: Fork a repository and modify a file

### 1. Fork the pyOpenSci practice GitHub repository

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.

:::{todo}
Create an animated gif showing how to fork a repo
:::


:::{tip}
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.
:::

Once you have submitted your issue with the proposed changes, one of the package developers will review the issue and either:

* Suggest changes to your proposed edits or
* Encourage you to submit a pull request with the two identified changes.

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.
45 changes: 45 additions & 0 deletions github-git/4-edit-commit-files.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
jupytext:
text_representation:
extension: .md
format_name: myst
format_version: 0.13
jupytext_version: 1.16.4
kernelspec:
display_name: Python 3 (ipykernel)
language: python
name: python3
---

# Your first edits to a file in your fork

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!

## Make the changes that you said you would make in the issue opened above

After you have forked the repo and received the OK to move forward with your pull request:

* Open the file you want to change in your fork.
* Make the edits that you want to make to the file
* Commit the changes that you made to the file. Important: try to use a short descriptive commit message that describes what you have changed:
*
> fix: fixed numerous typos in the filename.py file
> fix: updated the code to align with PEP 8 syntax
> fix: fixed typo in docstring text

::::{admonition} What is a commit??

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.



:::{figure} /images/github/git-commits-files.png
:alt: Alt here

:::

::::

:::{todo}
It might be cool to show first contributions like my first on to nbconvert could be interesting? Other people might have examples too
:::
22 changes: 4 additions & 18 deletions github-git/github-social-platform.md
Original file line number Diff line number Diff line change
@@ -51,27 +51,11 @@ Effective communication on GitHub ensures a productive and respectful collaborat
_"What if we try this approach?"_ instead of _"This is wrong."_
- Acknowledge positive aspects alongside suggestions for improvement.







*********
:::{todo}
Move this to the pr page once I create it.

## 3. When Contributing to a Repository

### Submitting Issues
- **Search First**: Before creating a new issue, check if someone else has already reported it.
- **Be Clear**: Provide a detailed, reproducible example when reporting bugs.
- **Be Constructive**: Avoid blaming or harsh criticism. Instead, frame your concerns as suggestions.

Example:
_Not Constructive_: "This feature is broken and useless."
_Constructive_: "I encountered an issue when using this feature. Here's the error and steps to reproduce it."





### Opening Pull Requests
@@ -80,3 +64,5 @@ _Constructive_: "I encountered an issue when using this feature. Here's the erro
- **Be Open to Feedback**: Expect to receive suggestions for improvement and revise your pull request accordingly.

Example Pull Request Description:

:::
24 changes: 12 additions & 12 deletions github-git/intro.md
Original file line number Diff line number Diff line change
@@ -69,26 +69,16 @@ https://www.youtube.com/watch?v=eWxxfttcMts
:::


:::{toctree}
:caption: Background
:maxdepth: 2
:hidden:

Use GitHub With Friends (vs. by yourself) <self>
What is Git/GitHub <what-is-git-github>
GitHub Social platform <github-social-platform>
:::


:::{toctree}
:caption: Contribute to Another Repo
:maxdepth: 2
:hidden:

0. The path to your first contribution <0-first-contribution>
0. Your contributing path <0-first-contribution>
1. Get to know the repo <1-get-to-know-repo>
2. Identify what you want to work on <2-identify-issue>
3. Fork GitHub Repo <3-fork-repo>
4. Edit & commit files <4-edit-commit-files>

:::

@@ -108,3 +98,13 @@ Clone a GitHub Repo <5-clone-repo>
Navigate the Social Dynamics of GitHub <github-social-platform>

:::

:::{toctree}
:caption: Background
:maxdepth: 2
:hidden:

Use GitHub With Friends (vs. by yourself) <self>
What is Git/GitHub <what-is-git-github>
GitHub Social platform <github-social-platform>
:::
1 change: 1 addition & 0 deletions github-git/what-is-git-github.md
Original file line number Diff line number Diff line change
@@ -35,6 +35,7 @@ Related to open science, GitHub:

By combining Git’s version control with GitHub’s collaborative features, you can manage code efficiently while supporting openness, transparency, and truly open collaboration.

(what-is-git)=
## What is git?

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**.
Binary file added images/github/git-commits-files.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/github/github-contributing-file.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading