Contributing

Important

Please note that this section is based on the contribution guidelines used in [CoBMo](https://github.com/TUMCREATE-ESTL/cobmo)

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.7.
  • 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 bug or 2) publishing a new release.
  2. development - 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 taken from fledge.config as fledge.config.config['paths']['results'].
    • When saving results with timestamp, use fledge.config.get_timestamp().
    • 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.