Developer Notes

Here we gather important notes for the developing of oemof and elements within the framework.

We highly encourage you to contribute to further development of oemof. If you want to collaborate see description below or contact us.

Install the developer version

To install the developer version two steps are necessary:

git clone git@github.com:oemof/oemof.git
sudo pip3 install -e /path/to/the/repository

Newly added required packages (via PyPi) are installed by performing a manual upgrade of oemof. Therefore, run

sudo pip3 install --upgrade -e /path/to/the/repository

Documentation

See the developer version of the documentation of the dev branch at readthedocs.org.

Collaboration with pull requests

To collaborate use the pull request functionality of github.

How to create a pull request

  • ...
  • ...
  • Tests must run, see ...
  • Name the related team within the title of the pull request, like “solph: pull request for new feature within solph”.
  • Assign a team member.

Tests

  • ...
  • ...

Style guidelines

We mostly follow standard guidelines instead of developing own rules. So if anything is not defined in this section, search for a PEP rule and follow it.

Docstrings

We decided to use the style of the numpydoc docstrings. See the following link for an example.

PEP8 (Python Style Guide)

  • We adhere to PEP8 for any code produced in the framework.
  • We use pylint to check your code. Pylint is integrated in many IDEs and Editors. Check here or ask the maintainer of your IDE or Editor
  • Some IDEs have pep8 checkers, which are very helpful, especially for python beginners.

Quoted strings

As there is no recommendation in the PEP rules we use double quotes for strings read by humans such as logging/error messages and single quotes for internal strings such as keys and column names. However one can deviate from this rules if the string contains a double or single quote to avoid escape characters. According to PEP 257 and numpydoc we use three double quotes for docstrings.

logging.info("We use double quotes for messages")

my_dictionary.get('key_string')

logging.warning('Use three " to quote docstrings!'  # exception to avoid escape characters

Naming Conventions

  • We use plural in the code for modules if there is possibly more than one child class (e.g. import transformers AND NOT transformer). If there are arrays in the code that contain multiple elements they have to be named in plural (e.g. transformers = [T1, T2,...]).
  • Please, follow the naming conventions of pylint
  • Use talking names
    • Variables/Objects: Name it after the data they describe (power_line, wind_speed)
    • Functions/Method: Name it after what they do: use verbs (get_wind_speed, set_parameter)

Using git

Branching model

So far we adhere mostly to the git branching model by Vincent Driessen.

Differences are:

  • instead of the name origin/develop we call the branch origin/dev.
  • feature branches are named like features/*
  • release branches are named like releases/*

Commit message

Use this nice little tutorial to learn how to write a nice commit message.

Testing

We use nosetests for testing. Make sure that all tests are successfull before merging back into the dev.

cd /path/to/oemof/
nosetests3 --with-doctest           # or
nosetests3 --with-doctest --rednose # if you like it

Issue-Management

Section about workflow for issues is still missing (when to assign an issue with what kind of tracker to whom etc.).