mirror of
https://github.com/genodelabs/genode.git
synced 2024-12-18 21:27:56 +00:00
63048fb89f
This also fixes some mixed content pages on genode.org and, thus, removes the ugly browser warning, e.g., on https://genode.org/documentation/release-notes/17.05.
193 lines
8.3 KiB
Plaintext
193 lines
8.3 KiB
Plaintext
|
|
======================
|
|
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:
|
|
|
|
:[https://genode.org/community/mailing-lists - Genode mailing lists]:
|
|
|
|
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:
|
|
|
|
:[https://github.com/genodelabs/genode/issues - 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:
|
|
|
|
:[https://genode.org/about/road-map]: Road Map
|
|
|
|
:[https://genode.org/about/challenges]: Future Challenges
|
|
|
|
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:
|
|
|
|
:[https://github.com/genodelabs - Genode Repository at GitHub]:
|
|
|
|
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:
|
|
|
|
:[https://genode.org/documentation/developer-resources/coding_style]:
|
|
Coding Style Guidelines
|
|
|
|
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:
|
|
|
|
:[https://genode.org/community/gca.pdf - Genode Contributor's Agreement]:
|
|
Genode Contributor's Agreement (GCA)
|
|
|
|
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.
|
|
|