Contribute to Project Pythia via GitHub¶

Overview:¶

1. Suggest a change
2. Make the edits
3. Create a Pull Request

Prerequisites¶

• 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