Skip to content

Release process

Mondo is released on a monthly basis around the first of the month. Additional releases are run ad hoc. All Mondo releases are available here.

Videos outlining this process are available here.

Initial setup:

These steps will be done only once, when setting up your computer for Mondo release.

Generate token

  1. Follow the instructions here to generate the GitHub token.

Set-up your path:

  1. In terminal, create a "tools" directory in your home directory: mkdir ~/tools. Note that we are creating a directory in your user directory, not in your Mondo directory (FYI, ~/ refers to your home directory in Mac or Linux systems). This directory can in the future contain various tools, such as ROBOT and scripts necessary for release processes.
  2. Lastly, ensure that your ~/tools directory is added to your path. If you are using zsh (as shown in the terminal window title), create your path:
  3. nano ~/.zshrc
  4. paste the following line into the file, usually at the very end: export PATH=/Users/torosa/tools:$PATH(instead of "/Users/torosa", use your path to the tools directory)
  5. save (by hitting control+o and then enter) and close (control+x)
  6. in the terminal, type: source ~/.zshrc; this reloades the .zshrc file.
  7. Open a new Terminal window before you continue.

install gh :

  • make sure you have installed 'brew' here
  • brew install gh

Releases

All release products are described on the OBO page and Mondo website.

  • the mondo-with-equivalent edition uses OWL equivalence axioms directly in the ontology. Note this makes it harder to browse in some portals, but this edition may be preferable for computational use. The owl edition also includes axiomatization using CL, Uberon, GO, HP, RO, NCBITaxon.
  • the primary release versions (mondo.owl, mondo.obo) are simpler, lacking owl equivalence axioms from Mondo classes to terms from other databases; instead, xrefs are used for linking these terms. If the ID is one of Orphanet, OMIM, DOID or EFO then the xref precisely shadows the equivalence axiom.
  • The mondo-with-equivalents json edition has all owl equivalencies as well as all xrefs to other disease sources.

The release mondo.owl will look like this in Protege: How release looks in Protege

Mondo release workflow

Note: While the release is running, don't shut your laptop or switch between repos or branches in GitHub, as this will stop the release.

Normalization step (BEFORE the release process)

  1. It is always a good idea to normalize the ontology after bulk changes. It is also good to normalize the ontology before a release
  2. The commands to use are:
    sh run.sh make NORM
    mv NORM mondo-edit.obo
  3. Move the changes to a branch and create a pull request and wait for the checks to pass.
  4. Merge the PR and continue with the release.

Prepare the release

  1. Do a docker pull: docker pull obolibrary/odkfull:dev
    • note, this step should not be required anymore.
  2. Pull master, create a branch, and navigate to the mondo/src/ontology folder on your computer
  3. Run command: sh run.sh make IMP=false all -B
    • note, this takes 1+ hour(s)
    • note that we are using the dev image as it is always up to date with the Python dependencies.
  4. Review before the next step:
    1. Make sure you see ‘release finished’ after the command has run
    2. Open mondo.owl and mondo.obo and check the latest changes are there and it looks reasonable
  5. Run sh run.sh make prepare_release_direct
    1. reports files will be created after running this command.
  6. Commit changes to a branch
    1. Commit the changes on the branch (you should already be on a branch)
    2. Do a pull request (PR)
    3. Wait for GitHub Actions/QC to pass
    4. Merge PR
  7. Note: review can be supported by the following files:
    • src/ontology/reports/mondo_release_diff.md
    • This file include a summary of the new terms, updated definition, new obsoletion, etc...
    • There is now a new QC section up top, ---START LOG: to ---END LOG:. Review the text and delete it from the file if there is no suspicious output.
    • note that this file is 'gitignore', ie one only sees it if they are the one running the release.
    • src/ontology/reports/difference_release_base.md
    • similar to the file above, this file include new terms, updated definition, etc, but also update in mappings, subclass of, subsets, etc.

Initial Setup:

Make sure the initial setup (see above) has been done:
1. Download the obo-simple-diff.pl script to the "tools" directory 1. go into the tools directory 2. type wget https://github.com/cmungall/obo-scripts/blob/master/obo-simple-diff.pl 3. Note that if you have a new computer, you might need to install 'wget' using brew install wget 1. you can see whether you have wget installed by taping wget -V. If it is installed, the version will be reported 1. set-up your path to the tools directory. 1. see top of this document 1. Generate token 1. see top of this document 1. Ensure you have gh installed: brew install gh. For other ways to install, see here.

Deploy Release

  1. login to GitHub via the command line: gh auth login. The command line will give you a series of prompts:
? What account do you want to log into? **Answer**: GitHub.com
? What is your preferred protocol for Git operations? **Answer**: HTTPS
? Authenticate Git with your GitHub credentials? **Answer**: Yes
? How would you like to authenticate GitHub CLI? **Answer**: Login with a web browser

! First copy your one-time code: **Note: There will be a code here and you'll need to enter this online**
Press Enter to open github.com in your browser...
✓ Authentication complete.
- gh config set -h github.com git_protocol https
✓ Configured git protocol
✓ Logged in as nicolevasilevsky
  1. cp ~/.token .token
  2. make GHVERSION=vYYYY-MM-DD deploy_release - note, this takes about 30 minutes
    • make sure you are in the src/ontology folder when running the above command
    • the date should be the date of the release in the format make GHVERSION=vYYYY-MM-DD deploy_release (for example, v2022-04-01) (very important: It should not necessarily be today, it is the day the release artifacts were created according to the IRIs. In order to find the right date, open mondo-base.obo and check version IRI, and use this date)
  3. Check these the release pages (make sure you replace the date correctly in the link in the output in the terminal):
    1. For example: https://github.com/monarch-initiative/mondo/releases/tag/untagged-2a6c39951f3210b62380
    2. Ensure that it says [name] (eg nicolevasilevsky) released this 1 days ago or now
    3. Ensure it has all release artifacts attached to it (there should be 22 assets in the draft. Note, there will be 24 after the release is published.)
    4. Check this file to ensure you see the expected changes (spot check a few changes): download the mondo.obo or mondo.owl from the asset list in the release.
  4. Write a description of the release
    1. Add the release description to the release tab:
      • All of the releases can be found under the releases tab.
      • To add a description of the release: - click edit - in the 'describe this release' section add a curated content from the file src/ontology/reports/difference_release_base.md. - the format of this files allows for open/close sections in the GH/Markdown format - titles should be updated to be less jargony to users - sections should be reorganized to add the new terms first, etc - some sections should not be added as they are confusing (e.g. mappings update, change in SubClasses,etc.) - when the list is too long, it should be shortened
      • click "save draft"
    2. IGNORE AS WE DO NOT DO THIS ANYMORE Add the summary of changes to changes.md.
      • go to changes.md
      • click edit
      • add the name of the new release and the content from the change log text file above.
      • commit to master Note: If you cannot find the "edit" button, you can update the changes.md file using atom, and committing to master.
  5. Click on "Publish release" (THIS IS NEW, the release, so far should have been in Draft state)

Check obsoletion candidates

With each release, a TSV should be generated with obsoletion candidates. Check that this tsv file is up-to-date here: https://github.com/monarch-initiative/mondo/blob/master/src/ontology/reports/mondo_obsoletioncandidates.tsv

Announce released

Mastodon

Notify the project manager that the release should be announced on Mastodon.

Email Mondo Users

Send an email to Mondo users: mondo-users@googlegroups.com
(Note - the recipients usually a picture of someone's pet to be included.) 1. Subject: The Mondo release is available 1. Update the Mondo release template with highlights of the releases, upcoming changes coming, announcements, etc.