This document contains guidelines for the collaboration in the bgpy python package.

Ready to contribute? Here's how to set up bgpy for local development.

1. Clone the repository: git clone https://github.com/munterfi/bgpy.git
2. Install the dependencies: poetry install
3. Create a feature branch for local development: git checkout -b feature/<the-feature-name> develop

4. Work locally on the feature, make sure to add or adjust:

   • entries in CHANGELOG.md
   • docstrings
   • tests for the feature
   • documentation

5. When finished with the feature, check that the changes pass:

poetry run pytest                               # Running tests
poetry run mypy --config-file pyproject.toml .  # Static type checks
poetry run flake8 bgpy tests                    # Code linting
cd docs && poetry run make html && cd ..        # Build documentation

Alternatively the script check.sh automates the steps above.

6. If tests are passed commit and push the changes:

git add .
git commit -m "Description of the changes."
git push origin feature/<the-feature-name>

7. Submit a pull request of the feature into the develop branch on GitHub.

The gitflow workflow uses two branches to record the history of the project. The master branch stores the official release history, and the develop branch serves as an integration branch for features. It's also convenient to tag all commits in the master branch with a version number.

Each new feature should reside in its own branch. But, instead of branching off of master, feature branches use develop as their parent branch. When a feature is complete, it gets merged back into develop. Features` should never interact directly with master.

Once develop has acquired enough features for a release, fork a release branch off of develop. When it's ready to ship, the release branch gets merged into master and tagged with a version number. In addition, it should be merged back into develop, which may have progressed since the release was initiated.

Dependencies and virtual environments are managed by poetry, do not edit the requirements manually! E.g. use poetry update && poetry build for version updating and poetry add <package_1> <package_2> for adding new ones.

Use snake_case for variable, argument and function/method name definitions. Also in tables that are written to the database avoid capital letters and dots (.) in column name definitions. For class names use UpperCaseCamelCase.

Create python documentation with docstrings in numpydoc convention.

Example:

def function_with_types_in_docstring(param1: str, param2: int = 10):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Parameters
    ----------
    param1 : str
        The first parameter.
    param2 : int, default 10
        The second parameter.

    Returns
    -------
    bool
        True if successful, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """

Add a header to CLI scripts according to the following template:

#!/usr/bin/env bash
# -----------------------------------------------------------------------------
# Name          :example_script.sh
# Description   :Short description of the scripts purpose.
# Author        :Full name <your@email.ch>
# Date          :YYYY-MM-DD
# Version       :0.1.0
# Usage         :./example_script.sh
# Notes         :Is there something important to consider when executing the
#                script?
# =============================================================================

Depending on the scope of your contribution add yourself to the authors field in the pyproject.toml file to ensure credits are given correctly.