mirror of
https://github.com/genodelabs/genode.git
synced 2024-12-20 06:07:59 +00:00
Updated doc/contributions.txt
With the recent change of Genode's development process and the switch to GitHub, the contributions document has become a bit outdated. I rewrote the document in a tutorial-like style and incorporated several practical hints, in particular related to the recommended use of Git.
This commit is contained in:
Norman Feske
parent
793cbff1f6
commit
e1af0b3292
@ -1,63 +1,199 @@
|
|||||||
|
|
||||||
======================
|
|
||||||
Contributing to Genode
|
|
||||||
======================
|
|
||||||
|
|
||||||
|
|
||||||
If you like to improve Genode in any way, you're more than welcome to
|
======================
|
||||||
contribute. A collection of ideas to enhance the current implementation can be
|
Contributing to Genode
|
||||||
found at the [http:/about/challenges - Challenges] page.
|
======================
|
||||||
|
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
:[http://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:
|
||||||
|
|
||||||
|
:[http://genode.org/about/road-map]: Road Map
|
||||||
|
|
||||||
|
:[http://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 you 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:
|
||||||
|
|
||||||
|
:[http://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 GPL with Genode Labs
|
Genode is publicly licensed under the terms of the GNU GPL with Genode Labs
|
||||||
maintaining the right to also distribute derivates to customers under
|
maintaining the right to also distribute derivates under different licenses or
|
||||||
negotiated licenses. [http:/about/licenses - Read more] about Genode Labs'
|
update the public License (i.e., eventually switching from GPLv2 to GPLv3).
|
||||||
dual-licensing business model. Contributions from outside Genode Labs can only
|
Contributions from outside Genode Labs can only be incorporated into Genode's
|
||||||
be incorporated into Genode's mainline development if each individual
|
mainline development if each individual contributor explicitly grants the
|
||||||
contributor expliticly grants the permission to redistribute his contributions
|
permission to let Genode Labs redistribute his contributions under non-GPL
|
||||||
under non-GPL licenses. This can be done in two ways:
|
licenses. This permission is granted by signing the Genode Contributors
|
||||||
|
Agreement:
|
||||||
|
|
||||||
# If you are planning a continuous involvement with the Genode development,
|
:[http:gca.pdf - Genode Contributor's Agreement]:
|
||||||
we recommend you to fill out and sign the
|
Genode Contributor's Agreement (GCA)
|
||||||
[http:gca.pdf - Genode Contributor's Agreement] (GCA). The GCA enables Genode
|
|
||||||
Labs to license Genode (including your contributions) under other licenses
|
|
||||||
than the GPL. The signed GCA covers all your future contributions.
|
|
||||||
|
|
||||||
# Alternatively, if you don't want to sign the GCA, you may submit
|
By signing the GCA, you don't lose any rights for your contribution. However,
|
||||||
your contributions under the [http:mit_license - MIT License]. This
|
you enable Genode Labs to license Genode (including your contributions) under
|
||||||
license is liberal and permits Genode Labs to use your contributions
|
licenses other than the GPL. The GCA needs to be signed only once. The signed
|
||||||
in open and closed-source projects.
|
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).
|
||||||
|
|
||||||
The major difference between both variants (and maybe an advantage of the GCA
|
Send a signed copy of the GCA to Genode Labs:
|
||||||
for you) is: The GCA permits only Genode Labs to relicense your contributions
|
|
||||||
whereas the MIT license effectively puts your code into the public domain.
|
:Postal address of Genode Labs:
|
||||||
|
|
||||||
|
*Genode Labs GmbH,*
|
||||||
|
*Tharandter Str. 13,*
|
||||||
|
*D-01159 Dresden,*
|
||||||
|
*Germany*
|
||||||
|
|
||||||
|
Alternatively, you may send a scanned copy of the signed GCA via email
|
||||||
|
to 'licensing@genode-labs.com'.
|
||||||
|
|
||||||
|
|
||||||
Development for Genode
|
Incorporating your work into the mainline source tree
|
||||||
######################
|
#####################################################
|
||||||
|
|
||||||
The Genode source code is available via file releases and a public source-code
|
Our goal with the 'genodelabs/master' branch is to keep the history as linear
|
||||||
repository (see the [http:/download - Download section] for details). Genode
|
as possible to make it easy for users of the framework to track the
|
||||||
Labs update the sources (incorporating community contributions) and announce
|
development.
|
||||||
new Genode releases. Therefore, the source-code repository is not meant for
|
To help us with accomplishing this goal, please make sure that your patch
|
||||||
active development but for convenient source-code update and tracking of
|
applies cleanly to 'genodelabs/master'.
|
||||||
changes between releases.
|
|
||||||
|
|
||||||
The advantage of this approach is that only code that meets Genode Labs's
|
For the continuous work on your private topic branch, please feel free to
|
||||||
quality measures (tests, stability) becomes part of an official Genode release.
|
commit as you like. For example, your commit sequence could look like:
|
||||||
The second (more legal) argument is that Genode Labs is obliged to ensure all
|
|
||||||
contributions fit our dual-licensing model.
|
! "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'.
|
||||||
|
|
||||||
|
|
||||||
Submission of your contribution
|
Important notice
|
||||||
###############################
|
################
|
||||||
|
|
||||||
As soon as you developed a patch you regard valuable to share with the
|
Please do not take the steps described herein too seriously. They are not
|
||||||
community, submit it for incorporation. First, decide which of the above
|
carved in stone. If you have suggestions for improving them, or if you feel
|
||||||
contribution licensing variants fits your needs best. Then, accompany your
|
staggered by all those rules, please let us know.
|
||||||
patch with a proper description of its changes and send it to the 'genode-main'
|
|
||||||
mailing list. Depending on your chosen licensing variant, you may have to state
|
|
||||||
that your source code is licensed under the MIT license.
|
|
||||||
|
|
||||||
Please, follow the developer discussion and possibly improve your patch. The
|
|
||||||
integration into Genode may take some time for review and testing at Genode
|
|
||||||
Labs.
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user