Make a pull request (PR)

A pull request, often shortened to PR, is the process by which code is contributed back to the central repository. It merges the changes from one branch into another. Often, the changes are being merged into the main or master branch, but PRs can be used to merge a branch with any other branch, both within the central repository and from a fork to the central repository.

Here you will have made a fork of the deafrica-sandbox-notebooks repository, so the PR consists of the following steps:

  1. Ensure your changes are on a branch that is up to date with digitalearthafrica:master

  2. Open a PR between your fork’s branch and digitalearthafrica/deafrica-sandbox-notebooks

  3. Describe the changes made in your branch

  4. Submit the PR for review

Since we have not made any substantial contribution to the repository in the previous example tutorials, this demonstration PR will not be submitted.

Check your remote branch is up to date

On your GitHub fork of the repository, use the branch dropdown to select the branch with the changes you want to propose. The header should say

This branch is XYZ commits ahead of digitalearthafrica:master.

Those commits are your proposed changes. If the branch is behind, perform a fetch upstream and merge.

Open a pull request

Click Contribute and select Open pull request.

Contribute button.

Describe your changes

This is an important step to communicate why you want to make changes to the repository. The deafrica-sandbox-notebooks has a default PR template: proposed changes should be summarised and the code quality checklist reviewed.

Open PR template.

Change the title to something more informative, and fill in the description.

At the top of the page, we can see the PR will request a merge from the user’s fork, from a branch called git-test, to the base repository digitalearthafrica/deafrica-sandbox-notebooks branch of master.

When the PR submission has been filled out, select Create pull request.

What happens next?

The PR becomes publicly visible. Depending on the repository settings, one or more contributors will need to review and approve the PR before it can be merged. This may involve editing your changes, or leaving comments or suggestions for improvement before merging can occur.

When should I make a PR?

PRs should do at least one of the following:

  • Fix an open issue on the repo

  • Improve existing code by removing typos or increasing efficiency

  • Expand on existing code

It is good practice to have a working familiarity with the repository before proposing large changes. If in doubt, get in contact with the repository owners.

GitHub wiki tutorial and other resources

A concise version of steps to open a PR can be found on the deafrica-sandbox-notebooks wiki.

Additionally, you may find this summary tutorial from dataschool.io useful.

Read error messages carefully and use Google (or your preferred search engine)! Forums such as Stackexchange have the answers to many Git problems.

Bonus: Make this tutorial better!

Contributions to this tutorial can be made through a pull request to the Digital Earth Africa Read the Docs repository at https://github.com/digitalearthafrica/deafrica-docs. It will then undergo the collaborative review process described above.

Digital Earth Africa Read the Docs content is mostly written in Markdown in Jupyter Notebooks with some formatting in ReStructuredText (RST).

Conclusion

Thanks for joining us on the journey towards Git literacy. We hope you found it useful!