Contributing#

If you are keen to contribute to this project, please follow these guidelines:

  • Before making any change, please first discuss via issue or email with the owners of this repository.

  • Development is based on Python 3.8.

  • Git branches follow the GitFlow principle.

  • Release versioning follows the Semantic Versioning principle.

Git branches#

Based on the GitFlow principle there are the following branches:

  1. master - Contains stable release versions of the repository. Only admins should send pull requests / commits to master when 1) fixing a critical bug or 2) publishing a new release.

  2. develop - This branch is intended as the main branch for development or improvement of features. Anyone can send pull requests to develop.

  3. feature/xxx - This branch is dedicated to developing feature xxx. The idea is to keep development or improvement works separate from the main develop branch. Once the work is finished, a pull request is created for feature xxx to be merged back into the develop branch.

Release versioning#

Every time the master branch changes, a new version number is defined according to the Semantic Versioning principle:

  1. New releases cause a changing version number in the first digit for major changes and in the second digit for minor changes (e.g. from 0.1.13 -> 0.2.0).

  2. Bugfixes cause a changing version number in the third digit (eg. from 0.1.12 -> 0.1.13)

Style guide#

  • Follow the PEP 8 Style Guide and check this PEP8 Explainer.

  • Variable / function / object / class / module names:

    • Names are verbose and avoid abbreviations.

    • Variable / function / object names are in lowercase and underscore_case (all letters are lowercase and all words are separated by underscores).

    • Variable / object names start with a lowercase letter.

    • Class / module names start with an uppercase letter and are in CamelCase (all letters are lowercase except for the first letter of new words).

  • Paths:

    • Use relative paths.

    • Use os.join.path("x", "y") instead of "x/y".

  • Docstrings / comments:

    • Docstrings should at minimum contain a short description of the function / class / module.

    • Docstrings and comments should only contain full sentences which conclude with a full stop (dot).

    • Docstrings follow Google style.

  • Exceptions / errors / warnings / debug info:

    • Use proper logging tools instead of print("Error: ...").

    • Use logging like logger.error("...") or logger.warning("...") or logger.debug("...").

  • Line length:

    • Line lengths should not exceed 120 characters.

  • Line breaks:

    • Use brackets to contain content spanning multiple lines.

    • Do not use the \ symbol for line breaks.

  • Quotes / strings:

    • Use single quotes '...' for parameters, indexes, pathes and use double quotes "..." for content, messages and docstrings.

  • Results / output files:

    • Store results / output files only in the results directory.

    • The results path should be obtained with mesmo.utils.get_results_path()

    • The content of the results directory should remain local, i.e., it should be ignored by Git and should not appear in any commits to the repository.

Release checklist#

Before pushing a new commit / release to the master branch, please go through the following steps:

  1. Run tests locally and ensure that all tests complete successfully.

  2. Ensure that change log entry has been added for this version in docs/change_log.md.

  3. Ensure that version numbers and year numbers have been updated everywhere:

    • setup.py (at version=)

    • docs/change_log.md

    • docs/conf.py (at copyright =)

    • CITATION.bib

    • LICENSE

  4. After pushing a new commit / release, create a tag and publish a new release on Github: https://github.com/mesmo-dev/mesmo/releases

  5. After publishing a new release, edit the latest Zenodo entry: https://doi.org/10.5281/zenodo.3562875

    • Set title to “MESMO - Multi-Energy System Modeling and Optimization”.

    • Set correct author names.

    • Set license to “MIT License”.