Contribute to Project Pythia via GitHub¶
Overview:¶
- Suggest a change
- Make the edits
- Create a Pull Request
Prerequisites¶
Concepts | Importance | Notes |
---|---|---|
What is GitHub | Necessary | |
GitHub Repositories | Necessary | |
Cloning and Forking | Necessary | |
Basic Version Control with git | Necessary | |
Issues and Discussions | Recommended | |
Branches | Necessary | |
Pull Requests | Necessary | |
Reviewing Pull Requests | Recommended | |
GitHub Workflows | Necessary |
- Time to learn: 30 minutes
Now that you have become more familiar with how to use Git and GitHub, you might have an idea or some material that you want to contribute to Project Pythia! The Project Pythia Contributor’s Guide describes the steps required to submit a PR to any of Project Pythia’s repos. Here, we will go through an example of submitting a PR to pythia-foundations
.
Suggest a change¶
One simple way to contribute is to fix a typo or suggest a change to one of the tutorials. For example, in the Computations and Masks with Xarray tutorial, let’s suggest a clarification that the sea surface temperature is called tos
in the dataset we are using.
We could open an issue to suggest this change in order to get feedback on the idea before we take the time to edit files, but since this is such a small change, let’s just create a PR.
Make the edits¶
We will follow the Forking Workflow described in the previous section of this tutorial, assuming pythia-foundations
has already been forked:
- Create a new branch with a descriptive name
- Make the changes and commit them locally
- Push to the remote repository
- Open a PR on GitHub
First, making the new branch,
git branch clarify-sst-tos
git checkout clarify-sst-tos
There are a variety of ways to make changes, depending on the type of file, as well as preference. Here we want to edit a Jupyter Notebook (file extension .ipynb
), so we can use JupyterLab. We find the file of interest at /core/xarray/computation-masking.ipynb
and add in some text:
After saving and exiting (and checking for changes with a git status
), we commit with the following:
git add core/xarray/computation-masking.ipynb
git commit -m 'Mention that SST is called tos in the model'
Then pushing to our remote aliased origin
:
git push origin clarify-sst-tos
Create a Pull Request¶
Now, going to our remote repo on GitHub, forked from pythia-foundations
, we see that recent changes have been made. By clicking on the “Compare & pull request” button, we can open a PR, proposing that our changes be merged into the main branch of ProjectPythia/pythia-foundations
.
Project Pythia has an automated reviewer system: when a PR is created, two members of the organization will be randomly chosen to review it. If your PR is not immediately ready to be approved and merged, open it as a draft to delay the review process. As shown in this Git Branches section, the “Draft pull request” button is found using the arrow on the “Create pull request” button.
Let’s add the content
tag and open this one as a draft for now:
For any PR opened in pythia-foundations
, there will be a few checks that need to pass before merging is allowed. Once the deploy-book / build
check has completed (which will likely take a few minutes), there will be a Deployment Preview URL commented by the github-actions bot that will take you to a build of the Pythia Foundations book with your edits. There you can ensure your edits show up as expected.
Once it is ready, click “Ready for review” to take it out of draft mode. Now we wait for any comments or reviews!
Summary¶
- You can contribute to Project Pythia by suggesting edits or adding content with a Pull Request