Contribute to ExerPy¶

What can I contribute?¶

ExerPy is developed as an open and free-to-use library by Sergio Tomasinelli, MSc. at the Chair of Energy Engineering and Climate Protection, Institute of Energy Engineering, Technische Universität Berlin. The project was conceived and is supervised by Prof. Dr.-Ing. Fontina Petrakopoulou. The goal is to make the project widely accessible and to establish it as a community-driven initiative in the future, in which users can request special components, flexible implementations of characteristics or custom equations — basically, whatever they can think of.

You are invited to contribute to this process, share your ideas and experience, and perhaps even start developing the software. Your solutions may help other users as well. Contributing to the development of ExerPy is straightforward and helps both the development team and the wider user community. Developing features is also a chance to engage in mutual code review and collaborate with other developers.

There are various ways to contribute to the development, including:

Contribute to the documentation¶

The easiest way to get involved in the development process is by improving the documentation. If you spot mistakes or think the documentation could be more precise or clearer in some sections, feel free to fix it and create a pull request on the GitHub repository.

If you come across typos or grammatical mistakes, or want to improve the clarity of the documentation, make your adjustments or suggestions and create a pull request for the dev branch. We appreciate your contribution!

Report bugs or add new features¶

If you encounter bugs in the software, you are warmly invited to report them using the issue tracker on the ExerPy GitHub page. Or, if you would like to suggest new features, e.g., additional components or similar enhancements, you can also open a discussion in the issue tracker. You are welcome to help develop missing features yourself if interested.

How can I contribute?¶

You will find the most important information concerning the development process in the following sections. If you have any further questions, feel free to contact us. We look forward to hearing from you!

Install the developer version¶

Fork the repository, clone your fork and install ExerPy with its development requirements in a virtual environment:

git clone https://github.com/YOUR_GITHUB_USERNAME/exerpy.git
cd exerpy
python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scripts\activate
pip install -e .[dev]

To stay in sync with the oemof/exerpy base repository, add the link to the oemof/exerpy repository as a remote to your local copy of ExerPy. We will call the remote “upstream”. Fetch the available branches; after that, you can pull changes from a specific branch of the oemof/exerpy repository (e.g., the “dev” branch in the example below).

git remote add upstream https://github.com/oemof/exerpy.git
git fetch upstream
git pull upstream dev --rebase

Use the --rebase option to avoid merge commits for every upstream pull. If you want to make changes to ExerPy, check out a new branch from your local dev branch. Make your changes, commit them, and create a pull request against the oemof/exerpy dev branch.

Collaboration with pull requests¶

To collaborate, use the pull request functionality of GitHub as described here: https://guides.github.com/activities/hello-world/

How to create a pull request¶

Fork the oemof/exerpy repository to your GitHub account.
Change, add or remove code.
Commit your changes.
Create a pull request and describe what you changed and why. Please use the pull request template we provide. It will appear when you click on “New pull request”.
Wait for approval.

Generally, the following steps are required when changing, adding or removing code¶

Read the Style guidelines and Naming Conventions and follow them.
Add new tests for what you have implemented.
Update the documentation (for example, to reflect new features or API changes).
Add a What’s New entry and your name to the list of contributors.
Check that all Tests still pass (see Tests).

Tests¶

The tests in ExerPy are divided into two main parts:

doc-tests (also used as examples for classes and methods/functions)
software tests (defined in the tests folder).

The tests contain code examples that expect a specific outcome. If the outcome matches the expectation, the test passes; if it differs, the test fails. You can run the tests locally by navigating into your local GitHub clone. The command check checks compliance with the PEP guidelines, the command docs tests the documentation build, and the command py3X runs the software tests with the selected Python version.

python -m tox -e docs
python -m tox -e check
python -m tox -e py311
python -m tox -e py312
python -m tox -e py313

If you want to have a look at the documentation build on your local machine, run the following command in your local ExerPy clone:

python -m sphinx docs/ docs/_build

Additionally, all tests will run automatically when you push changes to a branch that has an open pull request.

If you have further questions regarding the tests, we encourage you to reach out to us. We look forward to your inquiry.

Issue management¶

A good way to communicate with the development team is through issues on GitHub. If you discover a bug, want to suggest an enhancement or have a question about a specific development problem you’d like to discuss, please create an issue:

Describe your point clearly and accurately
Use the appropriate category tags from the list provided

Look at the existing issues to get an idea of how issues are used and structured.

Style guidelines¶

We mostly follow standard guidelines rather than creating our own rules. So if anything is not defined in this section, refer to a PEP rule and follow it.

Docstrings¶

We have adopted the numpydoc style for docstrings. See the following link for more information: numpy docstrings.

Code commenting¶

Code comments include block and inline comments in the source code. They help improve understanding of the code and should be used “as much as necessary, as little as possible”. When writing comments, follow the PEP 0008 style guide.

PEP8 (Python Style Guide)¶

We adhere to PEP8 for all code produced in the framework.
We format the code with Black and check it with Ruff, both with a line length of 120 characters. Run black src tests and ruff check src tests, or python -m tox -e check, before you open a pull request.
Some IDEs have PEP8 checkers, which are very helpful, especially for Python beginners.

Naming Conventions¶

We use singular names for modules and subpackages, even if they contain more than one class (e.g. heat_exchanger AND NOT heat_exchangers). Variables such as lists or arrays that hold multiple elements are named in the plural.
Please follow the naming conventions of PEP 8.
Use descriptive names
- Variables/Objects: Name them after the data they represent (power_line, wind_speed)
- Functions/Methods: Name them after what they do: use verbs (get_wind_speed, set_parameter)

Using git¶

Branching model¶

We mostly follow the Git branching model described by Vincent Driessen.

Differences are:

Instead of naming the branch origin/develop, we use origin/dev.
Feature branches are named like features/*
Release branches are named like releases/*

Commit message¶

Use this helpful commit tutorial to learn how to write clear and well-structured commit messages.

Documentation¶

The general implementation-independent documentation, such as the installation guide, flow charts, and mathematical models, is written in ReStructuredText (rst). The files can be found in the docs folder. For more information on ReStructuredText, see https://docutils.sourceforge.io/rst.html.