Creating a Pull Request#

In this guide we will be creating a pull request for the PyMC project.

Important

To follow this tutorial you will need to have your environment set up and have an idea of the changes you are planning to do.

To set up your environment you can follow the Local environment setup tutorial.
If you haven’t yet chosen an issue to work on, we recommend following the Your first contribution to PyMC tutorial.

Create a feature branch#

git checkout -b docstring_update

and check git indicates you the branch change was successful:

S'ha canviat a la branca nova «docstring_update»

Tip

Keep your branch names informative, use one branch per PR and never work on main.

Getting ready for the 2nd PR?

If you haven’t changed to a different branch, you’ll still be in the docstring_update one, but you don’t want to work there! Remember, one branch per PR.

Before starting to work on the new changes, move back to main, update your local copy and then create the new branch.

git checkout main
git fetch upstream
git rebase upstream/main
git checkout -b branch_for_2nd_pr

Commit the changes to git#

Add the changes to your local copy and give a name to the changes. Keep the name short yet informative, for example:

git commit -a -m "Updated pymc.Uniform docstring"

pre-commit will check and fix common formatting issues, and before doing this it needs to set up. So this can take a bit.

If all the checks pass, the end of the printed output will look like:

Check no tests are ignored...........................(no files to check)Skipped
Generate pip dependency from conda...................(no files to check)Skipped
No relative imports......................................................Passed
[docstring_update 2de5cc0a] Updated pymc.Uniform docstring
 1 files changed, 7 insertions(+), 5 deletions(-)

If some checks fail, there are two options:

pre-commit is able to fix the file

isort....................................................................Failed
- hook id: isort
- files were modified by this hook

Fixing /home/oriol/Documents/pymc/pymc/sampling.py

If this is the case for all fails, you only need to run the same command again, and now checks will pass:

git commit -a -m "Updated pymc.Uniform docstring"

pre-commit is not able to fix the file

No relative imports......................................................Failed
- hook id: no-relative-imports
- exit code: 1

pymc/sampling.py:89:from .aesaraf import change_rv_size, compile_pymc, inputvars, walk_model

If some fail has this message then it needs manual input. Ask on Discourse sharing this piece copied from your terminal. It needs to include the check name and all fail messages.

Upload (push) the changes to GitHub#

Then push the changes to your GitHub account with:

git push -u origin docstring_update

The output will look like:

S'estan enumerant els objectes: 40, fet.
S'estan comptant els objectes: 100% (40/40), fet.
Delta compression using up to 8 threads
S'estan comprimint els objectes: 100% (21/21), fet.
S'estan escrivint els objectes: 100% (22/22), 2.88 KiB | 2.88 MiB/s, fet.
Total 22 (diferències 15), reusat 0 (diferències 0)
remote: Resolving deltas: 100% (15/15), completed with 14 local objects.
remote:
remote: Create a pull request for 'docstring_update' on GitHub by visiting:
remote:      https://github.com/OriolAbril/pymc/pull/new/docstring_update
remote:
To github.com:OriolAbril/pymc.git
 * [new branch]        docstring_update -> docstring_update
La branca «docstring_update» està configurada per a seguir la branca remota «docstring_update» de «origin».

Create a Pull Request#

You will have noticed that the message already indicates how to open a PR and even provides a link. Click on the link (you might need to use right click plus “Open link”) and take a look at the page shown in your browser

Your screen at this point will be similar to:

pr_screen

Before clicking on the “Create pull request” button, check a couple things.

Make sure the title is informative. If you followed the advise here, it should already be as it defaults to the commit message.
Edit the description. You can remove all the points in the checklist except the one about the release notes. Then add a link to the issue you commented on.
If you have taken any notes while updating the docstring add them to the PR description.
Make sure the “Allow edits and access to secrets by maintainers” button is checked (it generally is checked by default)

You might also see a link to the CONTRIBUTING.md file. You don’t need to read it yet, this guide includes everything in the contributing guide that is relevant to this type of contribution. If your second PR is also on the pymc repo, then you should read the CONTRIBUTING.md guide there. However, if your second PR is to the pymc-examples repo instead, you have to read its (slightly different) CONTRIBUTING.md.

Click on “Create pull request” and celebrate for a bit 🎉, but the work is not finished.

Get ready for reviews#

Now you have to wait for someone on the PyMC team to review. If you have sent the PR during session hours, we’ll get to it fast (but not immediately, we might be reviewing someone else’s PR!), if you are doing this ahead of the session day, it will probably take several hours before someone sees it and reviews it.

We’ll probably make some extra comments about things to change, this is not a bad sign. We don’t expect you to know everything on the first try, and also, there might be further improvements like adding some See Also references that require a lot of familiarity with the code base.

If you need to address some comments, you will have to modify your local copy of the files (still on the same branch). Once you are finished, commit again (same command but different message):

git commit -a -m "address review comments"

Now you can push with:

git push

The remote and branch name are only needed the first time. After pushing you should see that the PR on GitHub has been updated.

:

Getting ready for the 2nd PR?

If you haven’t changed to a different branch, you’ll still be in the docstring_update one, but you don’t want to work there! Remember, one branch per PR.

Before starting to work on the new changes, move back to main, update your local copy and then create the new branch.

git checkout main
git fetch upstream
git rebase upstream/main
git checkout -b branch_for_2nd_pr

Your PR will be merged as soon as possible after that and you can properly celebrate your merged PR to PyMC! Thanks for contributing!