How to contribute

We welcome any effort to make HelenOS a better operating system. Here are some tips on what to do when you feel like contributing code. Make sure to subscribe to the HelenOS development mailing list and join the HelenOS IRC channel so that you can communicate with us efficiently.

A natural first prerequisite for any contribution is that you are able to compile HelenOS from sources and run it.

Ideas to work on

First of all, you need to know what to contribute or what to do. If you don't have your own idea, you can pick from open tickets. These includes both enhancements and bugs. Please note that most tickets do not have their difficulty specified. The Priority field is about how much we want this ticket to be completed and there are quite a lot minor tickets that required hours of work while some majors required few minutes.

There are few tickets marked with first-patch keyword: these are good starting points for your first contribution.

Ticket	Summary	Component
#43	Switch between virtual terminals using Alt+Fn	helenos/srv/console
#309	async_data_read_finalize returns EOK even with NULL data and nonzero size	helenos/lib/c
#355	Revive Doxygen reference	helenos/unspecified
#466	Command-specific tab completion in kernel console	helenos/kernel/generic
#496	Provide library implementations for common CRC's	helenos/lib/c
#581	strftime depends on fringe standard behavior for UTF-8 correctness	helenos/lib/c
#620	Make proper unit tests from tester/print tests	helenos/lib/c

If none of these tickets appeals to you, feel free to pick from the full list. And don't be afraid to ask on the mailing list if a particular ticket is a good candidate for the first tinkering with HelenOS. If you want to ask what is some nice ticket to start with?, please, specify the area you are interested in. Is it memory management? Networking stack? USB keyboards? Drivers for ARM? Be concrete, please.

We encourage you to file new tickets if you think that your great idea is missing on the list, but please do discuss the issue with us on the mailing list. Also please follow our guidelines for filing a ticket.

When you found or created a ticket that you would like to work on, make sure it is not owned by someone else. If the ticket is available, feel free to assign it to yourself. Otherwise you may want to ping the ticket owner on our mailing list to see if he or she is really working on the ticket. It can happen that the owner will gladly agree to pass the ticket ownership onto you.

Working on your branch

Now that you know what to do, you should go and create your private Bazaar branch of HelenOS. This is essential so that we can later merge your changes together with your initials in the development history of the branch. During the coding phase, keep in mind that we will require your changes to meet our coding style standards. It will happen to you from time to time that you will need to consult something with the other people from the project. Don't be shy and feel free to discuss things with us either in the mailing list or on IRC. For example, you can create a merge directive in Bazaar and send it to the mailing list for code review. Make smaller, logically related changesets rather than one huge changeset. Make sure that each changeset is accompanied by a clear commit message in English.

Submitting patches

If you have a simple change that you would like us to push to the mainline, you can submit it in the form of a patch. To submit your work as a patch, please follow these rules:

• Please avoid describing the patch manually (e.g. "this piece of code is to be inserted at line XYZ of file ABC") and use proper tools and formats as explained below.
• Always use unified diff format, as produced by running either bzr diff or diff -u.
• Test the patch before submitting and run make check -j 6 to see if the patch didn't break the build.
• Review the patch prior to submitting. Make sure it stays focused and does not introduce unrelated changes, including whitespace changes.
• Always send the patch to ​HelenOS-devel. Note that the mailing list is moderated, so make sure you are subscribed to it first or your message will be held up for moderation.
• Specifically, do not just attach the patch to a ticket as most developers won't be made aware of it
• Send the patch as an attachment. Inline patches will get broken by the MTAs.
• Choose a ​Bazaar identity and include it in the message so we can correctly attribute you with --author. This is important as not everybody wants their real e-mail address to appear in the commit log.

Alternatively you can provide us with a pointer to a public Bazaar branch (e.g. on ​Launchpad) from where we can pick the changes. In case you maintain a local branch with your changes and don't want to publish it, we can still merge from it using a Bazaar merge directive. A merge directive can be viewed as a better text patch which carries all the history and change information of your local branch while still being human readable. Once your local branch is ready to be merged, the merge directive can be created as follows:

$ bzr send -o my_merge.directive

Then send a brief message describing the change to our mailing list and attach my_merge.directive to it.

Compiling the system

Once you have your Bazaar branch ready you will want to compile the system so that you can test your changes. There are some common mistakes people make when trying to compile HelenOS so please read the compiling instructions carefully before running to us claiming that HelenOS does not build or does not work.

Integrating your changes

When you have tested your changes carefully and are confident enough that there are no bugs, you can ask one of us to merge your changes to our official repository. For that, you need to do one of two things. Either send us your final Bazaar merge directive or publish your branch in a publicly accessible location (e.g. Launchpad) so that we can merge from there. Note that publishing your branch is a good idea anyway because others can see your progress and your changes are backed up.

Eventually, if your changes look good to us, we will merge them and you will become part of the history. However, this final step might require some patience. We never merge any code only because we want the functionality. The overall design, the quality and the readability of the code has the same importance for us as the functionality. Properly and thoroughly reviewing the code takes time and time is something nobody has in abundance.