Where to begin

So you want to contribute to OpenQL? Or perhaps you’re employed to help maintain it? Great!

OpenQL has grown to be quite a large project, so you may be feeling a bit overwhelmed. I know I was. I’m assuming you already know what OpenQL is when you get here, otherwise please read through the user documentation first. But after that, where to begin…?

First of all, you should make sure that you’re able to build and test OpenQL on your own machine. So follow the Build instructions, and if you run into any problems, ask an existing maintainer or open an issue.

If you’ll be touching the Python API, you’ll also want to follow the instructions for building the documentation locally; there’s all kinds of generation magic from the API docstrings and documentation getters that might fall over if you change the wrong thing, and documentation generation is not currently tested by CI.

Once done, you’ll want to get some sort of IDE configured, so you can click through the code. I use CLion; they have free educational licenses for anyone with a university e-mail address, and it works okay.

Before changing anything, please read through the whole section on C++ coding conventions or CONTRIBUTING.md (the content is the same). This section describes more than just what should be capitalized and whether braces go on the same or the next line for consistency; it also goes over the general organization of the code, how to include things to make sure everything works everywhere, and what rules need to be followed with regards to the documentation dump_*() functions in order for the reStructuredText generators in docs/ to keep working.

Familiarize yourself with what’s available in the ql::utils namespace. This was added as a wrapper around the C++ standard library to offer additional runtime safety, improve type naming consistency with the non-STL types defined by OpenQL itself, and improve debugging. Depending on how used you are to C++ programming, you’ll probably either love it, hate it, or both. But please, please use it anyway, to keep OpenQL’s codebase consistent.

In general, please think twice if you feel the need to type std:: or include a standard library header directly. Most things are wrapped (although it’s virtually impossible to be complete).

Avoid adding new native dependencies. If you really need to, the build system should be made smart enough for things to work out of the box even if the dependency is not installed: your additions should automatically be disabled if they can’t be built, but the rest of OpenQL can. You can do this via preprocessor macros, but be aware that you can only use those in src! Files in include are public, and can thus be built with any preprocessor macro set when included by user C++ code. You can look at the code for unitary decomposition, MIP-based placement, or the visualizer if you’re not sure how to work with these constraints; those pieces of code all do this.

When you’ve added something, don’t forget to add yourself to CONTRIBUTORS.md!

These were just some general pointers I came up with on a whim, so this is most likely not complete. If you feel like something is missing, feel free to add to this list!