Contributing to Genode

You can contribute to the development of Genode in many different ways. First, you can contribute by trying out the framework and sharing your expectations and experience with us. This will help us to adjust the goals of the project according to the needs of its users. Please do not hesitate to discuss your ideas or suggestion at our mailing list. Maybe you stumbled over an issue that should be documented but isn't? Or the documentation contains errors with regard to content or spelling? Please let us know by raising the issue at the genode-main mailing list:

If you are interested in getting your hands dirty with working on the Genode code base or authoring additional documentation, you are more than welcome. For getting a rough overview of the current topics the Genode developers are pondering over, please have a look at the issue tracker:

You will see that the issues cover a large spectre ranging from minor fixes, over new features, to architectural changes. To pick the topic that suits you best, please consider introducing your intentions to the mailing list. We will gladly assist you with picking a topic to get you started.

Alternatively, you may like to have a look at our road map and future challenges to see the big picture of our developments and to get inspiration for your own activities:

Once you settled on a specific topic to work on, it is a good idea to get acquainted with the work flow and tools used by the project. The following sections are meant as a rough guide for working with Genode's mainline source tree in practice.

Clone the repository

The complete source code for both the Genode OS Framework and its documentation is managed via the project's public Git repository:

Also, most of the content of the genode.org website can be found in the form of plain text file within the repository.

If you intend to contribute changes to the mainline development, we recommend you to fork the Genode repository on GitHub. This will make it easy for everyone to track your activities, comment on your work.

Create a topic branch

As a rule of thumb, every line of development should have a corresponding issue in the issue tracker. This will be the place where we will discuss your ongoing work. If there is no issue for your topic, please create one. Once there exists the issue with a short description about what your line of work is about, create a new topic branch based on the genodelabs/master branch. For example,

 git checkout -b issue76

Work on your branch in the way you prefer. A long-winded history on your branch is not a problem because it will stay local to your repository. However, if you invest your time in maintaining a clean history, this is much appreciated.

Follow Genode's coding conventions

Genode's source code follows certain time-tested conventions regarding the coding style and code pattern, which are important to us. The coding style is described in the following document:

We know from experience that for new developers, adhering the coding style can be distracting and even annoying at times. To relieve you from keeping all those rules in your head, there is a tool for checking your code against the guidelines. The beautify tool is located at tool/beautify. When invoked with no arguments, it will provide you with brief usage instructions.

Writing a commit message

• Use the first line to summarize your commit using not more than 50 characters. This line will be displayed by various tools. So it should express the basic topic and eventually refer to an issue. For example:

   Add sanity checks in 'tool/tool_chain', fix #62
  

• If the patch refers to an existing issue, add a reference to the corresponding issue. If not, please consider opening an issue first. In the case the patch is supposed to close an existing issue, add this information using GitHub's conventions, e.g., by stating "fix #45" in your commit message, the issue will be closed automatically, by stating "ref #45', the commit will be displayed in the stream of discussion of the corresponding issue.

• After a blank line, add a description of the patch. For writing the description, keep the following questions in mind:

  • Why is the patch needed?

  • How does the patch achieve the goal?

  • What are known consequences of this patch? Will it break API compatibility, or produce a follow-up issue?

  The description should use a line with of about 75 characters. It may consist of multiple paragraphs separated by blank lines.

• Proof-read your commit message for spelling or grammatical errors.

• Reconsider the documentation related to your patch: If the commit message contains important information not present in the form of source-code comments, this information should better placed into the code or the accompanied documentation (e.g., in the form of a README file).

Genode Contributors Agreement

Before we will be able to incorporate your changes into Genode's mainline development, we require your permission to use your code.

Genode is publicly licensed under the terms of the GNU AGPLv3 with Genode Labs maintaining the right to also distribute derivates under different licenses or update the public License. Contributions from outside Genode Labs can only be incorporated into Genode's mainline development if each individual contributor explicitly grants the permission to let Genode Labs redistribute his contributions under non-AGPLv3 licenses. This permission is granted by signing the Genode Contributors Agreement:

By signing the GCA, you don't lose any rights for your contribution. However, you enable Genode Labs to license Genode (including your contributions) under licenses other than the AGPLv3. The GCA needs to be signed only once. The signed GCA covers your future contributions. Of course, you may cancel this agreement at your will. Please make sure that you are in the legal position to sign the GCA (i.e., by making sure that your contribution to Genode is in line with the Open-Source policy of your employer).

Send a signed copy of the GCA to Genode Labs. The postal address is Genode Labs GmbH, Dammweg 2, D-01097 Dresden, Germany.

Alternatively, you may send a scanned copy of the signed GCA via email to licensing@genode-labs.com.

Incorporating your work into the mainline source tree

Our goal with the genodelabs/master branch is to keep the history as linear as possible to make it easy for users of the framework to track the development. To help us with accomplishing this goal, please make sure that your patch applies cleanly to genodelabs/master.

For the continuous work on your private topic branch, please feel free to commit as you like. For example, your commit sequence could look like:

 "Implemented A"
 "Discarded a part of A because it was a bad idea"
 "Fixed spelling in comment"

If your history contains intermediate steps that are not meaningful to have in genodelabs/master, you may decide to clean up your history via git rebase -i. Ideally, each revision should represent a consistent state of your work that should (at least) build without errors. The refined history will then end up in the form of just a few commits. For the example above, all three commits should be merged into a single commit "Feature A" as the intermediate (and potentially bugged) revisions are not useful to have in genodelabs/main.

Important notice

Please do not take the steps described herein too seriously. They are not carved in stone. If you have suggestions for improving them, or if you feel staggered by all those rules, please let us know.