The official Git repository has two branches "master" and "staging".

Master branch

The master branch is the recommended branch for users of the framework. It is known to have passed quality tests. The existing history of this branch is fixed and will never change.

Staging branch

The staging branch contains the commits that are scheduled for inclusion into the master branch. However, before changes are merged into the master branch, they are subjected to quality-assurance measures conducted by Genode Labs. Those measures include the successful building of the framework for all base platforms and the passing of automated tests. After changes enter the staging branch, those quality-assurance measures are expected to fail. If so, the changes are successively refined by a series of fixup commits. Each fixup commit should refer to the commit it is refining using a commit message as follows:

 fixup "<commit message of the refined commit>"

If the fixup is non-trivial, change the "fixup" prefix to "squash" and add a more elaborative description to the commit message.

Once the staging branch passes the quality-assurance measures, the Genode maintainers tidy-up the history of the staging branch by merging all fixup commits with their respective original commit. The resulting commits are then merged on top of the master branch and the staging branch is reset to the new master branch.

Note that the staging branch is volatile. In contrast to the master branch, its history is not stable. Hence, it should not be used to base developments on.

Release version

The version number of a Genode release refers to the release date. The two-digit major number corresponds to the last two digits of the year and the two-digit minor number corresponds to the month. For example, "17.02".

Each Genode release represents a snapshot of the master branch taken at release time. It is complemented by the following commits:

• "Release notes for version <version>" containing the release documentation in the form of a text file at doc/release_notes,

• "News item for Genode <version>" containing the release announcement as published at the genode.org website,

• "Version: <version>" with the adaptation of the VERSION file.

The latter commit is tagged with the version number. The tag is signed by one of the mainline developers.

Each developer maintains a fork of Genode's Git repository. To facilitate close collaboration with the developer community, it is recommended to host the fork on GitHub. Open a GitHub account, use GitHub's web interface to create a new fork, and follow the steps given by GitHub to fetch the cloned repository to your development machine.

In the following, we refer to the official Genode repository as "genodelabs/genode". To conveniently follow the project's mainline development, it is recommended to register the official repository as a "remote" in your Git repository:

 git remote add genodelabs https://github.com/genodelabs/genode.git

Once, the official repository is known to your clone, you can fetch new official revisions via

 git fetch genodelabs

Topic branches

As a rule of thumb, every line of development has a corresponding topic in the issue tracker. This is the place where the developers discuss and review the ongoing work. Hence, when starting a new line of development, the first step should be the creation of a new topic.

The new topic should be accompanied with a short description about the motivation behind the line of work and the taken approach. The second step is the creation of a dedicated topic branch in the developer's fork of Genode's Git repository.

 git checkout -b issue<number> genodelabs/master

The new topic branch should be based on the most current genodelabs/master branch. This eases the later integration of the topic branch into the mainline development.

While working on a topic branch, it is recommended to commit many small intermediate steps. This is useful to keep track of the line of thoughts during development. This history is regarded as volatile. That is, it is not set in stone. Hence, you as developer do not have to spend too much thoughts on the commits during the actual development.

Once the work on the topic is completed and the topic branch is going to get integrated into the mainline development, the developer curates the topic-branch history so that a short and well-arranged sequence of commits remains. This step is usually performed by interactively editing the topic-branch history via the git rebase -i command. In many cases, the entire topic branch can be squashed into a single commit. The goal behind this curating step is to let the mainline history document the progress at a level of detail that is meaningful for the users of the framework. The mainline history should satisfy the following:

• The relationship of a commit with an issue at the issue tracker should be visible. For this reason, GitHub's annotations "Issue #n" and "Fixed #n" are added to the commit messages.

• Revisiting the history between Genode releases should clearly reveal the changes that potentially interest the users. I.e., when writing the quarterly release notes, the Genode developers go through the history and base the release-notes documentation on the information contained in the commit messages. This works best if each topic is comprised by a few commits with meaningful descriptions. This becomes hard if the history contains too many details.

• Each commit should represent a kind of "transaction" that can be reviewed independently without knowing too much context. This is hardly possible if intermediate steps that subsequently touch the same code are present as individual commits.

• It should be easy to selectively revert individual topics/features using git revert (e.g., when trouble-shooting). This is simple when each topic is represented by one or just a few commits.

Coding conventions

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

Writing a commit message

Commit messages should adhere the following convention. The first line summarizes the 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 "Issue #45", the commit will be displayed in the stream of discussion of the corresponding issue.

After a blank line, a description of the patch follows. The description should consider the following questions:

• 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?

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