Pull Requests

Overview

Teaching: 15 min
Exercises: 10 min

Questions

• How do I contribute changes to someone else’s project?

Objectives

• Contribute changes that are within your hosted repository back to the original one.

Pull requests are a method of merging commits between repositories that have been forked. GitLab calls them “merge requests” but they are exactly the same thing. We will continue to call them “pull requests” in these lessons. Often they are abbreviated as PR.

You can fork any repository that you have at least read-access to, start implementing an enhancement, fixing bugs or typos, improving documentation, etc. When you feel you are done with your improvement, you open a pull request.

Like Issues each pull request gets a unique ID, a title and an initial comment. Conversations are possible by posing additional comments. In addition to that, all commits that have been made to the forked repository that are not already in the origin repository will be attached to the pull request.

The owner of the original repository (or any developer who has been granted sufficient rights by the owner) can merge the commits of the pull request into the original repository from the website and thereby close the pull request.

Submit a Pull Request

1. Go to your forked repository on the website.
2. Clone it to your Desktop using git clone ... in the Unix Shell:

   $ git clone git@github.com:<Your_GitHub_Username>/testing_demo.git
   $ cd testing_demo
   $ ls
   

   more_files  mean.py  README.md  Workflow.md
   

3. Copy the file test_mean.txt from the more_files directory to the root of the repo as test_mean.py. (the same folder that contains README.md and mean.py).
4. Add the file test_mean.py, make a commit and push to GitHub:

   $ cp more_files/test_mean.txt  ./test_mean.py
   $ git add test_mean.py
   $ git commit -m "adding unit tests"
   $ git push origin main
   

5. Go back to the GitHub website and open a pull request (button: [New Pull Request]). Make sure to open the pull request towards the instructor’s fork of the repository.

Choose the Right Branch

When creating a pull request you have to choose the correct repositories:

1. base-fork - the repository to which the changes should be merged.
2. head-fork - the repository from which the changes should be merged. Some repositories have multiple branches (lines of development.) Make sure you select the right ones.

Look at the list of commits as well as the changes (diffs) below to make sure your settings are correct.

Make Sure Your Pull Request can be Merged

When opening a new pull request you will wither see: “✓ Able to merge” or: “✘ Can’t automatically merge”.

The second can happen when commits have been made (or merged) to the original repository since it has been forked.

In this case:

1. merge the current state of the original repository into the fork,
2. resolve the merge conflicts
3. test that your contribution still works as expected
4. now open the pull request.

Contribution Guidelines

If you are trying to contribute changes to a project, first check if there is a Contribution Guide. It is often a document called CONTRIBUTING, CONTRIBUTING.md or similar and is located in a repository’s root, docs, or .github directory.

In this guide the project’s maintainers can describe how they like to receive contributions and things that they pay special attention to, for example:

• code must follow a certain coding style
• code must have proper documentation
• code must have associated unit tests
• all tests must pass
• pull requests must be made towards a certain branch

But it often also contains things like:

• Links to external documentation, mailing lists, or a code of conduct.
• Community and behavioral expectations.

Please be polite and follow the Contribution Guide. Your pull request likely won’t be accepted until it follows the guidelines. Therefore you might as well follow the steps right away.

If your own project accepts contributions from other developers, consider creating a CONTRIBUTING of your own.

Key Points

• Pull requests are used to merge commits between repositories that share a common ancestor.

• Like issues contributors and maintainers can communicate via comments.

• Commits that are pushed to the branch that is to be merged become part of the PR.

• Once a maintainer is satisfied with the contribution, they merge the pull request.

• Pull requests are closed by either merging or rejecting them.