Contributing to Omnis libraries

GitHub is built for collaboration and offers a well-defined practice for contributing changes to someone else’s code. This process works very well with the JSON export in Omnis Studio 8.1, and this guide will walk you through this process.

Overview

Contributing to someone else’s repository on GitHub usually follows these steps:

  1. Copy, or fork, their repository for your changes
  2. Download, or clone, your copy of the repository
  3. Import their code
  4. Add your changes to their code
  5. Commit your changes to your copy of the repository
  6. Push your changes back to your fork
  7. Ask the repository’s owner to merge your changes back into the original repository

Prerequisites

Fork the repository

Unless a repository’s owner grants you permission, you cannot modify their repository directly. Instead, you make a copy of their repository and modify that copy. This copy is called a fork and has two unique properties.

  1. The fork is owned by you.
  2. The fork is linked to the original repository.

Each of these properties provides a specific benefit:

  1. Because you own the fork, you can make any change you like to it.
  2. Because the fork is linked to the original, GitHub makes it easy to share changes in the fork back to the original repository. This sharing process is called a Pull Request and is explained below.

How to fork a repository on GitHub

  1. Go on GitHub to the repository to be forked.
  2. Click on the button Fork. fork repository

Clone forked repository

Once you have the fork, you need to clone the fork to your local computer to get the (JSON) source. Follow these steps to clone your fork using the GitHub Desktop app.

  1. Navigate to your fork on github.com.
  2. Click on the green button Clone / Download. Clone or download repository
  3. A popup appears. Click Open in Desktop. Open repository in Desktop
  4. You will be prompted permission to open the GitHub app. Click Allow.
  5. The GitHub app opens with a window Clone a Repository. Clone in GitHub app
  6. (Optional) You can change the folder in which the repository will be cloned. Click on Choose to correct this.
  7. Click on Clone.

Import Library into Omnis

Next you can create a library from the source in your local copy of the fork using Omnis Studio.

  1. Open Omnis Studio.
  2. Click in the Studio browser on New Lib From JSON. New Lib From JSON
  3. Click on the … button next to ‘JSON Tree Path’. New lib JSON tree
  4. Go to the folder in the repository where the file library.json resides and click on Choose.
  5. Click on the … button next to Library Folder and choose a folder where the Library has to be created.
  6. Click on Import…. If there are any errors occuring check the Troubleshooting section below for more information.

Update forked repository

Make your changes directly in the library you imported. When you’re satisfied with those changes and want to share them back to the original repository, they first need to be added and uploaded (pushed) to the forked repository.

Update JSON tree

Click Update JSON tree in the Studio Browser. This will export the changed Omnis code to JSON. Update JSON Tree

Commit and push to forked repository

Use the GitHub app to commit and push the changes to the fork repository with the steps below

  1. Open the forked repository in the GitHub app
  2. Review your changes and enter a summary and a description and click Commit to master. GitHub app commit
  3. Click on ‘Push to origin’ to upload the changes to repository on GitHub.

Create pull request

The final step is to notify the owner of the original repository that you have made changes and want them to be merged into their repository. This notification is called a Pull Request because you’re requesting that the repository’s maintainer pull your changes back to the source.

  1. In the GitHub app click on the menu Branch and then on Create pull request. This opens GitHub in the browser (If menu option is grayed out. See Troubleshooting section). GitHub create pull request
  2. Click Create pull request. GitHub web create pull request
  3. Enter a descripton for the pull request.
  4. And click Create pull request.
  5. It is now to the owner of the original repository to descide if he accepts the changes. See the About pull requests documentation of GitHub for more informtion.

Troubleshooting

Errors at importing and exporting libraries

Output Library already exists

Most likely the choosen folder for the libary is the same as the one cloned from the forked repository. Either rename the existing library, remove it or choose another folder.

Import requires external library to be open

This means the library to be exported / imported is dependent on another library. Resovle this by first opening/importing the other library in Omnis Studio, then import the dependent library.

Unable to create pull requests

If the menu line Create pull requests is grayed out, then probably the repository is added as a local repository to the app. To enable the ‘Create pull requests’ menu line the repository has to be cloned from GitHub from within the GitHub app.

Published 27 October 2017 by H.P. Noppe