Pull Requests

Prerequisites

Participants will need to have access to the following resources and tools prior to the training:

• GitHub account - register for a free GitHub account here
• Install GitHub Desktop Please make sure you have some kind of git client installed on your machine. If you are new to Git, please install GitHub Desktop
• Protege - Install Protege 5.5, download it here

Preparation (optional)

• Review tutorial on Contributing to Ontologies
• See 'How to' guide on Pull Requests

What is delivered as part of the course

Description: How to create and manage pull requests to ontology files in GitHub.

Learning objectives

• How to create a really good pull request
• GitHub Pull Request Workflow
• How to find a reviewer for your pull request in an open source environment
• How to review a pull request
• How to change a pull request in response to review
• How to update from master
• Resolve conflicts on branch

Contributors

• Nicole Vasilevsky
• Nico Matentzoglu

Tutorials

Monarch OBO training Tutorials

Pull Requests Part 1

Pull Requests Part 2

How to create a really good pull request

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). A contributor creates 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.

How to write a great descriptive title

When committing a pull request, you must include a title and a description (more details in the workflow below.) Tips below (adapted from Hugo Dias):

• The title of the PR should be self-explanatory

• Do: Describe what was changed in the pull request

• Example: Add new term: MONDO:0100503 DPH5-related diphthamide-deficiency syndrome`

• Don't: write a vague title that has very little meaning.

• Example: Add new term

• Don't: use the branch name in the pull request (sometimes GitHub will offer this as a default name)

• Example: issue-5024

What kind of information to include in the description

• Describe what was changed in the pull request
• Explain why this PR exists
• Make it clear how it does what it sets out to do. E.g., Does it edit the ontology-edit.owl file? Does it edit another file(s)?
• What was your motivation for the chosen solution?
• Use screenshots to demonstrate what has changed. See How to guide on creating screenshots

Example:

General tips

• Do:
• Follow the Single Responsibility Principle: The pull request should do only one thing.
  • Note: sometimes a small edit can change a lot of code, for example, if you want to change all of the created_by annotations to dc:creator. That's okay.
• The pull request should be atomic: it should be small and self contained with simple changes that affect a little code a possible
• Whenever possible, break pull-requests into smaller ones
• Commit early, commit often
• Include specific information like the ID and label for terms changed. Note, you can easily obtain term metadata like OBO ID, IRI, or the term label in Protege by clicking the three lines above the Annotations box (next to the term name), see screenshot below. You can also copy the IRI in markdown, which is really convenient for pasting into GitHub.

• Don't:
• Make additional changes on a single PR that goes beyond the scope of the ticket or PR. For example, if you are adding a new term, don't also fix definitions or formatting for other terms.

GitHub Pull Request Workflow

Update the local copy of the ontology

1. In GitHub Desktop, navigate to your local ontology directory of your ontology
2. Make sure you are on the master/main branch and click Pull origin (or Fetch origin)

Create a New Working Branch

1. When starting to work on a ticket or making edits to an ontology, you should create a new branch of the repository to edit the ontology file.
2. Make sure you are on the master branch before creating a new branch. Please do not create a new branch off of an existing branch (unless the situation explicitly calls for it).
3. To create a new branch, click on Current Branch and select New Branch

1. Name your branch. Some recommended best practices for branch name are to name the branch after the issue number, for example issue-206. If you are not addressing a ticket per se, you could name the branch: 'initals-edits-date', e.g. nv-edits_2022-07-12, or give it a name specific to what you are doing, e.g. fix-typos-2022-07-12.

Continuing work on an existing Working Branch

1. If you are continuing to do work on an existing branch, in addition to updating master, go to your branch by selecting Current Branch in GitHub Desktop and either search for or browse for the branch name.

Video Explanation

A video is below.

1. OPTIONAL: To update the working branch with respect to the current version of the ontology, select Branch from the top menu, Update from master. This step is optional because it is not necessary to work on the current version of the ontology; all changes will be synchronized when git merge is performed.

Editing an ontology on a branch

1. Create a new branch, open Protege. Protege will display your branch name in the lower left corner (or it will show Git: master)

1. Make necessary edits in Protege.

Committing, pushing and making pull requests

1. Review: GitHub Desktop will display the diff or changes made to the ontology.
2. Before committing, view the diff and ensure the changes were intended. Examples of a diff are pasted below. Large diffs are a sign that something went wrong. In this case, do not commit the changes and ask for help instead or consider discarding your changes and starting the edits again. To discard changes, right click on the changed file name and select Discard changes.

Example diffs:

Example 1 (Cell Ontology):

Example 2 (Mondo):

Write a good commit messages

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 detailed 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. NOTE: You can use the word ‘fixes’ or ‘closes’ in the commit message - 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. ‘Fixes’ and “Closes’ is case-insensitive and can be plural or singular (fixes, closes, fix, close).

1. If you don’t want to close the ticket, just refer to the ticket # without the word ‘fixes’ or use ‘adresses’ or 'addresses'. The commit will be associated with the correct ticket but the ticket will remain open.

2. Push: To incorporate the changes into the remote repository, click Commit to [branch name], then click Push.

Make a pull request (PR)

1. You can either make a pull request (PR) directly from GitHub Desktop, or via the GitHub web browser.
2. To make a PR from GitHub Desktop, click the button 'Create Pull Request'. You will be directed to your web browser and GitHub repo.
3. Click Create Pull Request.

1. If your PR is a work-in-progress and not ready for review, you can save it as a draft PR and convert it to a PR when it is ready for review.

1. If you do not create a PR directly from GitHub Dekstop, you can go to your GitHub repo and you will see a yellow banner on top that notifies you of a pending PR.
2. Navigate to the tab labeled as ‘Code’. You should see your commit listed at the top of the page in a light yellow box. If you don’t see it, click on the ‘Branches’ link to reveal it in the list, and click on it.

1. Click the green button ‘Compare & pull request’ on the right.
2. You may now add comments, if applicable and request a reviewer. See section below on reviewers.
3. You can see the diff for your file by clicking 'Files Changed'. Examine it as a sanity check.
4. Go back to the Conversation tab.
5. Click on the green box ‘Pull request’ to generate a pull request.

How to find a reviewer for your pull request in an open source environment

1. Publicly managed ontologies do not have a structure in place to automatically deal with PRs.
2. If you make a PR to an open source project, you should open a separate social channel to the developers to notify them of your PR (e.g. find the project mailing list, Slack, etc.). You should introduce yourself and give some context.
3. Depending on the level of your permissions for the repository, you may or may not be able to assign a reviewer yourself.
4. If you have write access to the repository, you can assign a reviewer.
5. Otherwise, you can tag people in the description of your pull request.

6. Tips for finding reviewers:

7. An ontology repository should have an owner assigned. This may be described in the ReadMe file or on the OBO Foundry website. For example, the contact person for Mondo is Nicole Vasilevsky.

8. The primary owner can likely review your PR or triage your request to the appropriate person.
9. If you are addressing a specific ticket, you may want to assign the person who created the ticket to review.

How to review a pull request (PR)

If you are assigned to review a pull request, you should receive an email notification. You can also check for PRs assigned to you by going to https://github.com/pulls/assigned.

What kind of person do we need for what kind of pull request?

It depends on what the pull request is addressing. Remember the QC checks will check for things like unsatisfiable classes and many other checks (that vary between ontologies). Your job as a reviewer is to check for things that the QC checks won't pick up and need human judgement.

• If it is content changes, like adding new terms, or reclassifying a term, an ontology curator could review your PR.
• If the PR is addressing quality control or technical aspects, one of the ontology semantic engineers would probably be a good fit.

• If you don't know who to assign, we recommend assigning the ontology contact person and they can triage the request.

• To review a PR, you should view the 'Files changed' and view the diff(s). You can review changes in a pull request one file at a time.

• While reviewing the files in a pull request, you can leave individual comments on specific changes.

Example:

Things to look out for when reviewing a PR:

1. Make sure the changes made address the ticket. In the example above, Sabrina addressed a ticket that requested adding a new term to Mondo, which is what she did on the PR (see https://github.com/monarch-initiative/mondo/pull/5078).

2. Examples of things to look for in content changes (like adding new terms or revising existing terms):

3. Poorly written definitions
4. Missing or misformatted database cross-references
5. Incorrectly scoped synonyms

6. appropriate annotations

7. Make sure there are not any unintended or unwanted changes on the PR. See example below. Protege reordered the location of a term in the file.

1. Check that the logic is correct. This can be a difficult thing to do. Some tips:
2. Open the branch in Protege and examine the hierarchy in Protege
3. Compare the logic that was use to the logic used in an existing term
4. If the ontology uses Design Patterns, ensure the logic is consistent with the Design Patterns
5. Ask an expert in ontology logic to help review the PR
6. Remember there is no magic bullet to ensuring an ontology is logically sound, but do the best you can

Adding your review

1. After you finish reviewing each file, you can mark the file as viewed. This collapses the file, helping you identify the files you still need to review.
2. A progress bar in the pull request header shows the number of files you've viewed.
3. You can leave comments and requests for changes on the PR inline for on the PR when viewing the 'Files changed'.
4. You can add a single comment, or start a review if you have multiple comments.

5. After reviewing the file(s), you can approve the pull request or request additional changes by submitting your review with a summary comment.

6. Comment (Submit general feedback without explicit approval)

7. Approve (Submit feedback and approve merging these changes)

8. Request changes (Submit feedback that must be addressed before merging)

9. In addition or instead of adding inline comments, you can leave comments on the Conversation page. The conversation page is a good place to discuss the PR, and for the original creator to respond to the reviewer comments.

Inline commits

GitHub added a 'suggested Changes' feature that allows a PR reviewer to suggest an exact change in a comment in a PR. You can add inline comments and commit your comment using 'inline commits'. Read more about it here.

1. Go to the 'Files changed' tab of a pull request
2. Hover over the line you want to fix, and a blue box with a plus sign appears near the gutter on the left
3. Click that to display the normal line comment form
4. Click the button with a plus and minus sign, it adds a suggestion block to the comment text area with the existing text

1. You can make changes to the text inside the suggestion box. Note that you can add context for your suggested changes outside of the suggestion block
2. When you create the comment, it will show up to the maintainer as a diff
3. The maintainer can see what changes you are suggesting and accept them with a click

When are you done with your review?

If you review the PR and the changes properly address what was described in the description, then it should be sufficient. Not every PR needs comments, it can be approved without any comments or requests for changes. Feel free to ask for help with your review, and/or assign additional reviewers.

Some of the content above was adapted from GitHub Docs.

How to change a pull request in response to review

1. Check out your branch in GitHub Desktop and open the file in Protege.
2. Make the suggested changes.
3. Check the diff.
4. Commit your changes on your branch.
5. Note, you do not need to create another PR, your commits will show up on the same PR.
6. Resolve the comments on the PR.
7. Notify the reviewer that your PR is ready for re-review.

How to update from master

1. In GitHub Desktop, navigate to your branch.
2. In the top file menu, select Branch -> Update from master.

Resolve conflicts on branch

Conflicts arise when edits are made on two separate branches to the same line in a file. (reference). When editing an ontology file (owl file or obo file), conflicts often arise when adding new terms to an ontology file on separate branches, or when there are a lot of open pull requests.

Conflicts in ontology files can be fixed either on the command line or using GitHub Desktop. In this lesson, we describe how to fix conflicts using GitHub Desktop.

Fix conflicts in GitHub desktop

1. In GitHub Desktop, go to your master/main branch and fetch pull.
2. Go to branch with conflict.
3. Pull branch.
4. Branch -> update from master.
5. Open in Sublime or Atom.
6. Make changes in file (open the ontology file in a text editor (like Sublime) and search for the conflicts. These are usually preceded by <<<<<. Fix the conflicts, then save).
7. In GitHub Desktop, continue merge.
8. Push.
9. In terminal: open [ontology file name] (e.g.open mondo-edit.obo) or open in Protege manually.
10. Save as (nothing should have changed in the diff).
11. Check the diff in GitHub online.

Video Explanation

Watch a video below with an example fixing a conflict in the Mondo ontology file.

Some examples of conflicts that Nicole fixed in Mondo are below:

Further regarding

Gene Ontology Daily Workflow

Gene Ontology Editing Guide

GitHub Merge Conflicts

• Resolving a merge conflict on GitHub
• Git merge conflicts

The anatomy of a perfect pull request

Blog post by Hugo Dias

Suggesting Changes on GitHub - includes description of how to make inline commits