Contributing

Contributions are welcome, especially extensions to the documentation and new services. Please follow the guide provided below to ensure that your work will fit into the BEMCom repository. Please feel free to open up an issue to discuss your ideas before starting to work on something.

Developing Services

Any BEMCom application can easily be extended with new services. If you plan to contribute a service to this repository please ensure you have considered the following points:

  1. That you have understood the fundamental concepts of BEMCom before you start.

  2. That you use one of the service templates if one exists for the service type and programming language. Please also consider to develop a service template if none exists but it would make sense. E.g. consider e.g. that you would like to implement a connector in a programming language for which no template exists. Splitting up the new connector into a template and the connector itself will likely introduce little overhead to the first connector, but will significantly reduce development effort for the second connector using the same programming language.

  3. That you have read and understood the message format before you start if you plan to implement a service template or a service that should directly interact with the broker. Also please verify that you will implemented the message format correctly and completely.

Implementation Rules

Here additional rules for for implementations in specific programming languages.

Python

Please follow these guidelines while implementing components in Python:

  • Readability counts! Thus, before you start: Read and understand PEP 8.

  • Documentation is Key: Try to document why stuff is done. Furthermore document what is done if that is not obvious from the code.

  • Docstrings: Every function/method/class should have a Docstring following the Numpy convention.

  • Provide tests for everything: Tests ensure that your code can be maintained and is not thrown away after the first bug is encountered. Unless you have very good reason, use pytest.

  • Use the right format: Use Black to format your code. Maximum line length is 80 characters.

Code will only be accepted to merge if it is:

  • Formally correct: Flake8 shows no errors or warnings. Again using a maximum line length of 80 characters.

  • Logically correct: All tests pass and all relevant aspects of the code are tested.