BaSyx / Developer / Contributing

Contributing

For a contribution to Eclipse BaSyx, several requirements have to be met. They will be detailed in the following.

Eclipse Contributor Agreement

Eclipse BaSyx is using the Eclipse environment for managing code. Due to this, a valid Eclipse Account with a signed Eclipse Contributor Agreement is needed.

Usage of Gerrit

Eclipse BaSyx uses Gerrit for code review. This has several benefits, e.g. allowing to update an already committed changeset to address code review remarks. In the following, a small outline of using Gerrit is giving. For more details, see here

Preparing Your Commit

For this a git commit hook needs to be installed that automatically adds information needed by Gerrit, namely the change id.

To install this commit hook, execute

curl -Lo .git/hooks/commit-msg https://git.eclipse.org/r/tools/hooks/commit-msg

by command line (e.g. Git Bash on Windows) in the folder where the Eclipse BaSyx repository resides. Please note that you have to repeat this step whenever you do a fresh check out of the repository.

Additionally, your commit message does need to contain a "signed of by" message. This can be added by using the -s parameter when creating the commit. Below an example of a commit message containing both a change id and a signed of by is given:

 Fixes bug: TCP server threads were never closed
* Adds appropriate unit test
Change-Id: I360b92cb786d005d8f06a5d98a433c6da67c7930
Signed-off-by: Frank Schnicke <frank.schnicke@iese.fraunhofer.de>

Pushing your Commit

Your git credentials are different to your Eclipse credentials. To retrieve your git credentials, log into Gerrit. Then, click on your name in the upper right corner and select Settings. There, you'll find your git username in the section HTTP Password. Additionally, use Generate Password to create your password.

Last, a commit does need to be pushed to Gerrit in a specific way. Instead of directly pushing to ${branch}, instead a push to refs/for/${branch} is expected. Afterwards, the commit will be processed by our Continuous Integration and will be manually reviewed, too. Finally, either your changeset gets accepted and merged or points of improvement will be given.

Updating your Commit

In the case of you wanting to update your changeset, either due to remarks by reviewers or any other reason, you have to amend your commit, either by git commit --amend or by rebasing. Please make sure that the change id is not modified. Afterwards, push your commit by using git push origin ${commit SHA}:refs/for/${branch}. The commit SHA can for example be obtained by using git log.

Developing new Components

There are multiple ways of implementing BaSys 4.0 conforming components.

Extending Existing Interfaces

For each component, there exist interfaces that can be implemented to realize e.g. new backends. These interfaces integrate seamless in the REST-API-Provider. Additionally, the already defined test suites for the different component types can easily be reused.

In consequence, this is the easiest and fastest way of introducing new components.

Conforming to the REST-API

If the interfaces provided by BaSyx can't be used (e.g. because the component is implemented in a programming language currently not supported by BaSyx), it has to be ensured that the component is conforming to the defined REST-API and behavior.

For this, BaSyx provides a Technology Compatibility Kit (TCK). The TCKs for the components can be found in the repository in components/tck. For each component, there exists a TCK. Each TCK allows to generate a jar file that tests component functionality of arbitrary http endpoints. Each jar can be called in the following way:

java -jar $JAR $HTTP_ENDPOINT

where $JAR is the name of the component's TCK jar and $HTTP_ENDPOINT is the endpoint on which the component's REST API is available.