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.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.results_path.

  • When saving results with timestamp, use fledge.config.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.