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.
If you are new to HelenOS, especially a first time contributor, make sure to discuss your idea on the mailing list first so that we can agree on the overall design or that it is something we want to pursue before diving into the implementation.
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 |
|---|---|---|
| #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.
There are also long-running tasks that may be a good choice for new contributors:
- Implementing unit tests for modules or functions that lack it
- Improving existing unit tests
- Filling in missing doxygen docs
- Improving the command reference
Working on your branch
Now that you know what to do, you should go and create your private Git clone of HelenOS. The easiest way is to fork HelenOS on GitHub. 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 patch and send it to the mailing list for code review. Alternatively, you can open a PR on GitHub.
Make smaller, logically related commits rather than one huge commit. Make sure that each commit is accompanied by a commit message that follows the example below. The first line should be a short description of WHAT the commit does written in imperative mood. It should not exceed 50 columns of text width and the trailing period should be omitted. The next line should be empty. Optionally, you may provide additional paragraphs that explain WHY the change was made. The text should not exceed 72 columns of width. Note that some editors will help you follow these rules by text highlighting. The entire commit message must be written in English.
An example commit message may look like this:
Make INTERFACE_LOC_SUPPLIER parallel
Location service sometimes needs to be able to process requests in
parallel in order to avoid deadlock.
Submitting patches
If you have a change that you would like us to merge into HelenOS, the easiest way is to create a PR (pull request) at GitHub. Alternatively, you can point us to a public Git branch of yours by sending an e-mail to HelenOS-devel.
You can also send us a traditional 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
git diffordiff -u. - Test the patch before submitting and run
make check -j 6to 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.
- You must let your identity be known to us so that we know who contributed to HelenOS and who to give credit to.
Compiling the system
Once you have your Git 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 create a PR at GitHub or publish your branch in a publicly accessible location (e.g. GitHub) 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.
