Contributing to the MIDIMonster

We’re glad you found this page, because it means you like the project so much you want to help us in making it even better!

That’s great news, because open source software only exists because people decide to get active :)

There’s a wide range of topics you can help the project with, you don’t need to be able to program or design to help - though if you can, that’s great, we’ve got plenty of stuff needing that, too!

Community

Starting up with a new tool, especially one as powerful as the MIDIMonster, can be downright scary. There’s lots to learn, some things may not work the first time, the entire thing may seem really complex.

One of the easiest things that help the project is to join the community of users - both by using the MIDIMonster and hanging out in our communication channels - such as IRC, reddit, or Discord.

Since this is where a lot of new users gather to ask their questions, having experienced users be present to help them figure it out is a great help. Having their questions answered competently makes newcomers feel welcome and gets them on their feet quicker, advancing them on their own way to be an expert :)

Reporting bugs

Just like everyone else on this planet, the MIDIMonster developers are not perfect - and just like every other software on this planet, the MIDIMonster sometimes has bugs. We work hard to find them before they manifest in problems, but sometimes errors do slip through, or sometimes we’re not able to foresee every situation a particular backend may get used in.

We’re always happy to get useful bug reports, if possible with an example configuration and steps to reproduce the problem. This allows us to understand how the problem can be fixed quickly.

If you’re a programmer, we also really appreciate patches that fix the problem, but of course that’s optional and just reporting that you found a problem is a valuable contribution in itself!

Writing code

If you’re already comfortable with programming and would like to familiarize yourself with the MIDIMonster code base, go ahead and read the development guide as well as the (admittedly rather terse) API documentation. We take great care in writing readable code and commenting it thoroughly.

If you already have an idea of what you want to change, it’s normally best to try to understand what’s currently happening around the area your change is in (such as the affected backend, or the core component containing your intended target). Then you can make your changes and propose a pull request on GitHub or send a patch via Email. We will review the change and ultimately merge it if we think it works as intended :)

If you’re not yet sure about what issue exactly you want to tackle, take a look at the open issues or grep the code base for the words “TODO” and “FIXME”. We use these to indicate locations in the code that will require more attention at some point, and we usually document those locations with some additional information on what needs to be done.

We strongly recommend you talk to us before starting to write code, to avoid multiple people working on the same issue concurrently. Just pop by our IRC, join our Discord or simply open an issue on GitHub about the thing you want to do.

Sometimes, features are too far out of scope for the MIDIMonster core or even some backends. In those cases, sometimes it’s the best course of action to create a “contrib” program, that is, a program which only makes sense to use with the MIDIMonster (for example, a configuration generator).

Research

Developing a tool as versatile and powerful as the MIDIMonster takes a lot of research, both into the architectural side of software development as well as into the technical side, such as all the details of implementing a specific protocol.

If you have an idea for a new backend, a new technology to be implemented or a new device you want to control using the MIDIMonster, that’s a great start! We always like to hear new ideas! It’s even better if you start the research process and link to pieces of technical documentation that explain how to communicate with your new protocol or device in detail, or some reference implementation that may already be available. This saves the developers valuable time that is otherwise spent researching those specifics.

Writing & improving documentation

The coolest project in the world will not be used much if it doesn’t tell you what it can do, and how to do it. That’s why we put great effort into putting out a lot of content about how to use the MIDIMonster, how to write configurations, and how to use and configure our backends.

As we create new features and update or improve existing ones, sometimes we forget to update the documentation. If you notice any inconsistencies in the documentation and the behaviour you’re seeing, try to find out wether it’s a bug or a feature (for example, by opening a ticket), or - if you’re sure the documentation should be updated - just change the documentation to match the behaviour.

Most of our documentation, such as the MIDIMonster homepage, the knowledgebase and our example configurations are open for anyone to make improvements to. Just edit the files directly on GitHub, or clone them and open a pull request for your changes.

If you’ve created an easy-to-understand configuration that highlights some specific feature, consider adding it to our collection of example configurations in the main repository. Those will get shipped with the downloadable releases, so new users can take a look at what is possible, and can extend and modify them to quickly get their show running.

Document your use-case

If you have a cool show running with the MIDIMonster and would like to show it off, or you found a novel way to use the versatility of the MIDIMonster, consider writing about it! We provide the MIDIMonster Knowledge Base as a user-curated repository of things that can be done with the MIDIMonster, and interesting bits of information. If writing is not your strong suit, maybe making videos is more your thing? If it explains what you’ve done, we’re happy to embed your video in the knowledge base!

Spreading the word

Last in this list, but really important to any open source project: Tell your friends! Open source project live because people think they’re useful - if you don’t know about something, how would you know it’s useful?

We’re all volunteers, so we can’t really afford a marketing campaign that would bring awareness to the people we want to reach. So we rely on word-of-mouth from people like you, who are convinced that the MIDIMonster can help you realize your creative vision.

So tell your friends, tell people that ask about your setup, see if you can find creative new uses, create videos, create products using the MIDIMonster, whatever works for you :) Thank you so much!