Create a Pull Request in GitHub

This how-to gives guidance on how to make a Pull Request (PR). For more on PRs, and guidelines on what makes a good PR, see the GitHub 10 tips on Pull Requests guide.

Overview

GitHub workflows

A Git repo consists of a set of branches each with a complete history of all changes ever made to the files and directories. This is true for a local copy you check out to your computer from GitHub or for a copy (fork) you make on GitHub.

A Git repo typically has a master or main branch that is not directly edited. Changes are made by creating a branch from Master (complete copy of the Master + its history) (either a direct branch or via a fork).

Branch vs Fork

You can copy (fork) any GitHub repo to some other location on GitHub without having to ask permission from the owners.  If you modify some files in that repo, e.g. to fix a bug in some code, or a typo in a document, you can then suggest to the owners (via a Pull Request) that they adopt (merge) you your changes back into their repo. See the Appendix for instructions on how to make a fork.

If you have permission from the owners, you can instead make a new branch.

What is a Pull Request?

A Pull Request (PR) is an event in Git where a contributor (you!) asks a maintainer of a Git repository to review changes (e.g. edits to an ontology file) they want to merge into a project (e.g. the owl file) (see reference). Create a pull request to propose and collaborate on changes to a repository. These changes are proposed in a branch, which ensures that the default branch only contains finished and approved work. See more details here.

Committing, pushing and making pull requests

1. See these instructions on cloning an ontology repo and creating a branch using GitHub Dekstop.

2. Review: Once changes are made to the ontology file, they can be viewed in GitHub Desktop.

3. Before committing, check the diff. An example diff from the Cell Ontology (CL) is pasted below. Large diffs are a sign that something went wrong. In this case, do not commit the changes and consider asking the ontology editor team for help instead.

Example 1 (Cell Ontology):

Example 2 (Mondo):

1. Commit message: Before Committing, you must add a commit message. In GitHub Desktop in the Commit field in the lower left, there is a subject line and a description.

2. Give a very descriptive title: Add a descriptive title in the subject line. For example: add new class ONTOLOGY:ID [term name] (e.g. add new class MONDO:0000006 heart disease)

3. Write a great summary of what the change is in the Description box, referring to the issue. The sentence should clearly state how the issue is addressed.

4. To link the issue, you can use the word 'fixes' or 'closes' in the description of the commit message, followed by the corresponding ticket number (in the format #1234) - these are magic words in GitHub; when used in combination with the ticket number, it will automatically close the ticket. Learn more on this GitHub Help Documentation page about Closing issues via commit messages.

5. Note: 'Fixes' and "Closes' are case-insensitive.

6. If you don't want to close the ticket, just refer to the ticket # without the word 'Fixes' or use 'Addresses'. The commit will be associated with the correct ticket but the ticket will remain open. 7.NOTE: It is also possible to type a longer message than allowed when using the '-m' argument; to do this, skip the -m, and a vi window (on mac) will open in which an unlimited description may be typed.

1. Click Commit to [branch]. This will save the changes to the ontology edit file.

2. Push: To incorporate the changes into the remote repository, click Publish branch.

Make a Pull Request

1. Click: Create Pull Request in GitHub Desktop

2. This will automatically open GitHub Desktop

3. Click the green button 'Create pull request'

4. You may now add comments to your pull request.

5. The CL editors team will review your PR and either ask for changes or merge it.

6. The changes will be available in the next release.