Contributing to the MIDI Dictionary

We have opened the MIDI Dictionary for community contribution. The data contributed is available for public use at OpenMIDI.

We use Github to manage all the work being done. The main source of data for the MIDI Dictionary can be found in this repository.

Before doing any work, users will need to:

1. Open a Github account

2. Download and install Github Desktop. If you are not comfortable with command line, please download Github Desktop.

Once the above is set up and you are logged into Github, go to the main project and click on Fork.

Github will prompt you to select which account you want to fork to. Select your account.

After which, Github will process to clone the project into your account.

Once that is done, you’ll now have the entire repository in your account.

Go to Github Desktop and clone your project into your local computer. That means that the files that exist in the repository will now be in your local filesystem after cloning.

Enter your forked project URL into the text box and click Clone.

Github might prompt you on what you want to do with the project. For this, we want to contribute to the parent project.

Once done, use a text editor to open the project. Personally, I like to use Visual Studio Code.

In VS code, open your cloned project..

Create a new file in the appropriate folder. We label the folder by brand names. If the brand is not there, create a new folder and put your .yaml file there. In this example, I want to create a file for the Morningstar MC3.

The format of the file is YAML. You can find out more info about it here. You can also just copy an existing file’s content and paste it into yours, and edit from there. After you are done editing, just run it though a YAML Lint to ensure your syntax is correct.

After this is done, you’ll need to map your new file in mapping.json. Over here, I added a new line under Morningstar Engineering (please note the JSON syntax) where the name is the name that will be displayed in the dictionary, and the value is the name of your yaml file.

Once this is done and saved, go back to Github Desktop. You’ll see that all the new changes are tracked. How cool is that?

Commit your changes to the master branch with a clear description of what you have done.

Once committed, push your commit to origin. This means that your changes will be pushed to your project in the Github server

Once pushed, you’ll need to create a Pull Request. This means that you are asking the admins of the base repository (the one you forked from) to merge your commits into the theirs.

A browser window will open showing the changes you want to be pulled into the main repository. Click on Create Pull Request.

That’s it! Once this is done, we will receive a notification that a new Pull Request (or PR) is created. We’ll review the changes and make changes if necessary, and then merge it into the base repository. Your changes will then be reflected in the MIDI Dictionary and Open MIDI a few minutes later after the PR is merged.