Here you find important notes for developing 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.
To avoid problems make sure you have fully uninstalled previous versions of oemof. It is highly recommended to use a virtual environment. See this virtualenv tutorial for more help. Afterwards two steps are necessary to install the developer version:
git clone firstname.lastname@example.org:oemof/oemof.git pip3 install -e /path/to/the/repository
Newly added required packages (via PyPi) are installed by performing a manual upgrade of oemof. Therefore, run
pip3 install --upgrade -e /path/to/the/repository
To collaborate use the pull request functionality of github.
How to create a pull request¶
- Fork the oemof repository
- Create a pull request and describe what you will do and why
- Change, add or remove code
- Read the Style guidelines and follow them
- Add new tests according to what you have done
- Add/change the documentation (new feature, API changes …)
- Add a whatsnew entry and your name to Contributors
- Check if all tests still work including the example tests
Run the following test before pushing a successful merge.
nosetests -w "/path/to/oemof" --with-doctest python3 path/to/oemof/examples/oemof_full_check.py
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.
We decided to use the style of the numpydoc docstrings. See the following link for an example.
Code comments are block and inline comments in the source code. They can help to understand the code and should be utilized “as much as necessary, as little as possible”. When writing comments follow the PEP 0008 style guide: https://www.python.org/dev/peps/pep-0008/#comments.
PEP8 (Python Style Guide)¶
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
- 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)
So far we adhere mostly to the git branching model by Vincent Driessen.
- instead of the name
origin/developwe call the branch
- feature branches are named like
- release branches are named like
Section about workflow for issues is still missing (when to assign an issue with what kind of tracker to whom etc.).
The general implementation-independent documentation such as installation guide, flow charts, and mathematical models is done via ReStructuredText (rst). The files can be found in the folder /oemof/doc. For further information on restructured text see: http://docutils.sourceforge.net/rst.html.