Skip to content

Latest commit

 

History

History
137 lines (100 loc) · 4.97 KB

CONTRIBUTING.rst

File metadata and controls

137 lines (100 loc) · 4.97 KB

Contributing

This document contains guidelines for the collaboration in the glacier-flow-model python package.

Getting started

Ready to contribute? Here's how to set up glacier-flow-model for local development.

  1. Clone the repository: git clone https://github.com/munterfi/glacier-flow-model.git
  2. Install the dependencies: poetry install
  3. Create a feature branch for local development: git checkout -b feature/<the-feature-name> master
  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 .                               # Static type checks
poetry run flake8 glacier_flow_model tests      # Code linting
cd docs && poetry run make html && cd ..        # Build documentation

Alternatively the script check.sh automates the steps above.

  1. 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>
  1. Submit a pull request of the feature into the master branch on GitHub.

Trunk-based Development Workflow

The trunk-based development workflow uses one branch master to record the history of the project. In addition to the mainline short-lived feature or bugfix branches are used to develop new features or fix bugs.

Features

Each new feature should reside in its own short-lived branch. Branch off of a feature/<feature-description> branch from master. When a feature is complete, it gets merged back into master and the feature branch is deleted.

Bugfix

Each bugfix should reside in its own short-lived branch. Branch off of a bugfix/<bugfix-description> branch from master. When the fix is complete, it gets merged back into master and the bugfix branch is deleted.

Release

This packages uses semantic versioning. Once master has acquired enough features for a release, set the new version number of the in the pyproject.toml and the CHANGELOG:rst file. Commit and push to master and publish a new release on GitHub, which will trigger an action to build and publish the package to PyPi.

Dependencies

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.

Documentation and coding style

Naming convention

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.

Python docstrings

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/

    """

Script header template

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?
# =============================================================================

Credits

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