Ontology Editors Daily Workflow
- 1 Updating the local copy of the ontology with ‘git pull’
- 2 Creating a new working branch with ‘git checkout’
- 3 Continuing work on an existing working branch and dealing with conflicts
- 4 Loading, navigating and saving the Ontology in Protégé
- 5 Committing, pushing and merging your changes to the repository
- 5.1 Reviewing changes
- 5.2 Committing changes to the local branch
- 5.3 Pushing working branch to origin
- 5.4 Creating a Pull Request for your branch
- 5.5 Automated checks
- 5.6 Merging the Pull Request
- 6 Review Status
Updating the local copy of the ontology with ‘git pull’
- Navigate to the ontology directory of go-ontology: cd repos/go-ontology/src/ontology.
- If the terminal window is not configured to display the branch name, type
You will see:
* On branch [master] [or the name of the branch you are on] Your branch is up-to-date with 'origin/master'.
- If you’re not in the master branch, type:
git checkout master
- From the master branch, type:
git pull. This will update your master branch, with the files that are most current on GitHub, bringing in and merging any changes that were made since you last pulled the repository using the command git pull. You will see something like this:
~/repos/go-ontology(master) $ git pull remote: Counting objects: 26, done. remote: Compressing objects: 100% (26/26), done. remote: Total 26 (delta 12), reused 0 (delta 0), pack-reused 0 Unpacking objects: 100% (26/26), done. From https://github.com/geneontology/go-ontology 580c01d..7225e89 master -> origin/master * [new branch] issue#13029 -> origin/issue#13029 Updating 580c01d..7225e89 Fast-forward src/ontology/go-edit.obo | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) ~/repos/go-ontology(master) $
Creating a new working branch with ‘git checkout’
- You should never work on the master branch. When starting to work on a ticket, you should create a new branch of the repository to edit the ontology file.
- Make sure you are on the master branch before creating a new branch. If the terminal window is not configured to display the branch name, type
git statusto check which is the active branch. If necessary, go to master by typing
git checkout master.
- Create a new branch: type:
git checkout -b branch_namein the terminal window.
- Naming branches: we recommend using the string ‘issue-‘ followed by the issue number. For instance, for this issue in the tracker: https://github.com/geneontology/go-ontology/issues/13390, you would create a branch as follows:
git checkout -b issue-13390. Typing this command will automatically put you in the new branch. You will see this message in your terminal window:
~/repos/go-ontology/src/ontology(master) $ git checkout -b issue-13390 Switched to a new branch 'issue-13390' ~/repos/go-ontology/src/ontology(issue-13390) $
Continuing work on an existing working branch and dealing with conflicts
- If the terminal window is not configured to display the branch name, type:
git statusto check which is the active branch. If necessary, go to master by typing
git checkout master.
- Update master by typing
- To list existing local branches: type
git branch -l
- From the master branch, switch to your branch by typing
git checkout [branch name]
- Update the working branch with respect to the current version of the ontology (OPTIONAL) by typing
git pull origin master
- This step is optional because it is not necessary to work on the current version of the ontology.
- Usually, changes in the working branch will be synchronized with master when you merge the pull request.
- When you run the 'git pull origin master' command, 3 things can happen:
- All is OK: No action needed. You will get a message that the branch is 'Already up to date', followed by the normal prompt in your terminal window.
- Some changes have been imported that need to be merged into your branch: You may get a message requesting that you merge the master branch into your branch (note that 'merge' is a type of 'commit'). Git opens a text editor window (dependent on how which text editor is set up by default; instructions here are for the vi Editor; https://www.ccsf.edu/Pub/Fac/vi.html) with the following comment:
Merge branch 'master' of https://github.com/geneontology/go-ontology into issue-16057 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.
In the vi editor:
i(for 'insert'). This will put your cursor in the first line ("Merge branch...") and allow you to edit.
- Type the comment (for example, 'merged master')
- Exit: type
:q!to save changes and quit (q= quit, ! = save). You will get a message in the terminal that looks like this, followed by the normal prompt in your terminal window:
Auto-merging src/ontology/go-edit.obo Merge made by the 'recursive' strategy. src/ontology/go-edit.obo | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------- src/ontology/subsets/gosubset_prok.yaml | 2 +- src/ontology/subsets/mf_needs_review.yaml | 5 ++--- 3 files changed, 95 insertions(+), 29 deletions(-)
- This merges and commit the merged branch (master + your branch).
- 4. Type
git push origin mybranchto push your changes to the remote repository.
- There are conflicts that prevent git from merging
- In some cases, in particular when there are inconsistencies between your branch and master, (for example when new terms have been created since your branch was last updated, or terms were merged or obsoleted), this step is necessary. These problems are usually reported by the Travis checks.
- Sometimes when you do git pull origin master, the branch is found by git to have conflicts with master, which will lead to an error message in the terminal window (see next section).
- The version of the ontology in the local branch may be in conflict with master. In this case, the terminal will return a message that looks like this (for a branch named 'mybranch'):
- The problem with conflicts is that you cannot switch to another branch until they are resolved.
- NOTE: This is a delicate operation. Ask someone to review the changes if you have any doubts.
- To fix conflicts:
- Open the go-edit.obo file using your favorite text editor.
- Conflicts will be within tags like
<<<<<<< HEAD ... >>>>>>> hash number For example: <<<<<<< HEAD ======= id: GO:0019836 name: hemolysis by symbiont of host erythrocytes namespace: biological_process def: "The cytolytic destruction of red blood cells, with the release of intracellular hemoglobin, in the host organism by a symbiont. The host is defined as the larger of the organisms involved in a symbiotic interaction." [GOC:add, UniProtKB-KW:KW-0354] synonym: "haemolysis in host" EXACT  synonym: "hemolysin activity" RELATED  synonym: "hemolysis by symbiont of host RBCs" EXACT [CL:0000232] synonym: "hemolysis by symbiont of host red blood cells" EXACT [CL:0000232] synonym: "regulation of cytolysis of host cells by symbiont" EXACT [GOC:dph, GOC:tb] is_a: GO:0001897 ! cytolysis by symbiont of host cells is_a: GO:0052331 ! hemolysis in other organism involved in symbiotic interaction [Term] >>>>>>> e3d0e5afcd225e02722423ef17d2b2fa669a33f3
- Usually, what is within the
>>>>>>> hash, can be deleted.
- Save your changes.
- Commit by typing
git commit -i * -m 'fixed conflict' go-edit.obo
- Do a
git diff masterto make sure that the changes you have made are correct ('git diff' only will not do because you have already committed).
- If you have any doubt about the changes, delete the branch and start the work over. To do this, type
git checkout masterand delete the branch by typing,
git branch -d mybranch.
- If the branch is never pushed to origin, there is no impact of the main go-edit.obo file.
- If the changes are as expected, you can go ahead with the push and the further steps.
- Before launching Protégé, make sure you are in the correct branch. To check the active branch, type
- Open the go-edit.obo file: Click on the ‘File’ pulldown. The first time, you will have to navigate to repos/go-ontology/src/ontology. Once you have worked on the file, it will show up in the menu under ‘Open’/’Recent’.
- Click on the ‘Classes’ tab.
- Searching: Use the search box on the upper right to search for a term in the ontology. Wait for autocomplete to work in the pop-up window.
- Viewing a term: Double-click on the term. This will reveal the term in the ‘Class hierarchy’ window after a few seconds.
- Launching the reasoner: To see the term in the ‘Class hierarchy’ (inferred) window, you will need to run the ‘ELK reasoner’. Go to menu:
‘Reasoner’ > select ELK 0.4.3, then click ‘Start reasoner’. Close the various pop-up warnings about the ELK reasoner. You will now see the terms in the inferred hierarchy.
- After modification of the ontology, synchronize the reasoner. Go to menu:
‘Reasoner’ > ‘ Synchronize reasoner’
- NOTE: The only changes that the reasoner will detect are those impacting the ontology structure: changes in equivalence axioms, subclasses, merges, obsoletions, new terms.
- Saving: Use
File > Saveto save your changes.
Committing, pushing and merging your changes to the repository
Changes made to the ontology can be viewed by typing in the terminal window:
git diff. If there are changes that have already been committed, the full changes in the active branch relative to master can be viewed by typing
git diff master.
Committing changes to the local branch
Changes can be committed by typing
git commit -m ‘Meaningful message Fixes #ticketnumber’ go-edit.obo. The message ('-m') must be in either single or double quotes.
- For example:
git commit -m ‘hepatic stellate cell migration and contraction and regulation terms. Fixes #13390’ go-edit.obo
- This will commit the saved changes to the go-edit.obo file in your active branch. The terminal window will show something like:
~/repos/go-ontology/src/ontology(issue-13390) $ git commit -m 'Added hepatic stellate cell migration and contraction and regulation terms. Fixes #13390' go-edit.obo</code> [issue-13390 dec9df0] Added hepatic stellate cell migration and contraction and regulation terms. Fixes #13390 1 file changed, 79 insertions(+)</code> ~/repos/go-ontology/src/ontology(issue-13390) $ </code>
- The word ‘fixes’ is a magic word in GitHub; when used in combination with the ticket number, it will automatically close the ticket (in the go-ontology repo; if you are working on a ticket from a different repo the command will still go to the go-ontology repo and close a ticket there). In the above example, when the file is merged in GitHub, it will close issue number 13390. Learn more on this GitHub Help Documentation page about Closing issues using keywords.
- ‘Fixes’ is case-insensitive.
- If you don’t want to close the ticket, just refer to the ticket # without the word ‘Fixes’. The commit will be associated with the correct ticket but the ticket will remain open.
- 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.
Pushing working branch to origin
To add your branch to the remote repository, type:
git push origin mynewbranch.
git push origin issue-13390
- TIP: Once you have pushed your changes to the repository, they are available for everyone to see, so at this stage you can ask for feedback.
Creating a Pull Request for your branch
- In your browser, return to the GO Ontology repository on GitHub.
- Navigate to the tab labeled as ‘Code’ https://github.com/geneontology/go-ontology/code. You will see your commit listed at the top of the page in a light yellow box. If you don’t see it, click either on the ‘Branches’ link or on the 'branches' pull down menu to reveal it in the list (see screenshot).
Compare (last sanity check before pull request)
Click the green button
Compare & Pull requeston the right (see screenshot below). This will allow you to open a Pull Request, and determine if there are conflicts between your branch and master (if there are no conflicts, there will be a green check mark and the text 'Able to merge'.
The diff for your file is at the bottom of the page. Examine it as a sanity check.
Open the pull request
Click the green button
Create pull request(see screenshot below). This will start to compare your branch with master and initiate the Travis checks to find potential errors in your branch (for example: missing IDs, missing references for definitions, is_a incomplete, logical errors).
Request a review (optional)
You may now add comments and ask a colleague to review your pull request by selecting a reviewer in the ‘Reviewers’ list (e.g. @superuser1). The reviewer will be notified. Since the pull request is also a GitHub issue, the reviewer’s comments will show up in the comments section of the pull request, similarly to any other issue filed on the tracker.
- Wait for the Travis checks to complete (this can take a few minutes; see screenshot).
- If the Travis checks fail, you will see a red
xat the left of each of the checks. Go back to your local branch, correct the reported errors, commit them to the branch, and push to origin. The Travis checks will then start automatically (since the pull request has already been generated).
- If the Travis checks pass, you will see a green check mark at the left of each of the checks.
Merging the Pull Request
When (and only when!) the Travis checks are successful and if you're ready to integrate the changes in the main ontology file, merge the pull request, by clicking on the green
Merge pull requestbutton.
- Note that the reviewer should go ahead and merge the pull request if s/he agrees with the changes.
- Confirming the merge will close the ticket if you have used the word ‘fixes’ in your commit comment.
- You can now safely delete the branch, both in the repository and in your local repository.
Deleting the branch
- Delete your branch on the repository using the button on the right of the successful merge message.
- You may also delete the working branch on your local copy. Note that this step is optional. However, if you wish to delete branches on your local machine, in your terminal window:
- Go back to the master branch by typing git checkout master.
- Update your local copy of the repository by typing
git pull origin master
- Delete the branch by typing
git branch -d workingbranchname
git branch -d issue-13390
Last reviewed: August 8, 2018Back to: Ontology Editing Guide
~/repos/go-ontology (issue-14892)]$ git pull origin master From https://github.com/geneontology/go-ontology * branch master -> FETCH_HEAD Already up to date. ~/repos/go-ontology (issue-14892)]$