Contribute as a user

The documentation, examples and tutorials should be understandable and the code bug-free. As all user’s have different backgrounds, you may not understand everything or encounter bugs. In that case, PLEASE raise an issue here.

Consider labeling the issue using the flag bug or documentation / question.

Contribute as a developer

If you instead want to contribute new features or fix bugs yourself, we are more than happy.

Please also raise an issue and create a new branch labeled issueXY_some_name. Here, XY is the number of your issue and some_name is a meaingful description.

Once you’re feature is ready, create a pull request and check if the pipeline succeeds. Assign a reviewer before merging. Once review is finished, you can merge.

Before implementing or modifying modules, classes or functions, please read the following page.

Styleguide

We use PEP8 as a styleguide. Some IDEs (like PyCharm) automatically show you code that is not in PEP8. If you don’t have such an IDE, please read this page to get a better understanding of it.

Documentation

All created or modified function should be documented properly. Try to follow the structure already present. If possible, write a little doctest example into the docstring to make clear to user’s what the desired output of your function is. All non self-explanatory lines of code should include a comment. We use the pycharm-style for docstrings, e.g.

def foo(dummy):
    """
    Describe what the function does in here.
    The blank line below is necessary for the doc to render nicely.

    :param str dummy:
        Any parameter description
    :param int,float dummy2:
        A variable that may have two types
    """

Unit-Tests

Espacially when creating new functions or classes, you have to add a unit-test function. Open the test_module.py file in the \tests-directory and add a function to the class TestModulewith a name like test_my_new_function. If you create a new module, you have to create a new test_my_new_module.py file and follow the existing structure of the other test-files.

If you are not familiar with unit-tests, here is a quick summary:

Test as many things as possible. Even seemingly silly tests like correct input-format help prevent future problems for new users
use the self.assertSOMETHING functions provided by unittest. This way a test failure is presented correctly An error inside your test function will not be handeled as a failure but an error.
If the success of your test depends on the used device, you can use decorators like skip(), skipif(numpy.__version__<(1, 0), "not supported with your numpy version"), etc.
setUp() and tearDown() are called before and after each test. Use this functions to define parameters used in every test, or to close applications like Dymola once a test is completed.
See the unittest-documentation for further information

You can check your work by running all tests before commiting to git.

Pylint

With pylint we try to keep our code clean.
See the description in this repo on information on what pylint is and how to use it.